home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / modem / ic201c.zip / SCRIPT.DOC < prev    next >
Text File  |  1994-06-06  |  598KB  |  15,181 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                   Intellicomm (TM)
  7.                                        v2.01
  8.        Copyright (C) 1991-1994 Liberation Enterprises.  All rights reserved.
  9.        ---------------------------------------------------------------------
  10.                      INTELLICOMM SCRIPT LANGUAGE DOCUMENTATION
  11.        ---------------------------------------------------------------------
  12.  
  13.      This document should be used only after you have read the script intro-
  14.      duction in SCRTUTOR.DOC (included with Intellicomm).  If you haven't,
  15.      please start there first.
  16.  
  17.      It is very important that you read the 'introduction' sections in both
  18.      the SCRIPT COMMANDS AT A GLANCE and DETAILED COMMAND SUMMARIES sections. 
  19.      After you read the introductions, you'll have no trouble understanding
  20.      this documentation.  If you skip the introductions you may have a LOT of
  21.      trouble.
  22.  
  23.                                  TABLE OF CONTENTS
  24.  
  25.  
  26.      1.  SCRIPT COMMANDS AT A GLANCE . . . . . . . . . . . . . . . . . . .   1
  27.          1.1  Introduction . . . . . . . . . . . . . . . . . . . . . . . .   1
  28.          1.2  Video (Screen) and Cursor Commands . . . . . . . . . . . . .   1
  29.          1.3  Menu Handling  . . . . . . . . . . . . . . . . . . . . . . .   3
  30.          1.4  Keyboard Input and Output  . . . . . . . . . . . . . . . . .   4
  31.          1.5  Communications . . . . . . . . . . . . . . . . . . . . . . .   5
  32.          1.6  Icom Information / Script Variables  . . . . . . . . . . . .   8
  33.          1.7  Text (String) Handling . . . . . . . . . . . . . . . . . . .   9
  34.          1.8  Math Commands  . . . . . . . . . . . . . . . . . . . . . .    10
  35.          1.9  DOS and File Input/Output Commands . . . . . . . . . . . .    11
  36.          1.10  Date and Time . . . . . . . . . . . . . . . . . . . . . .    13
  37.          1.11  Script Flow / Decision-Making . . . . . . . . . . . . . .    13
  38.          1.12  Other Useful Commands . . . . . . . . . . . . . . . . . .    14
  39.          1.13  File Tagger Commands (Advanced use only)  . . . . . . . .    15
  40.  
  41.      2.  USING THE DETAILED COMMAND SUMMARIES  . . . . . . . . . . . . .    20
  42.          2.1  COMMAND Description  . . . . . . . . . . . . . . . . . . .    20
  43.          2.2  SUMMARY Description  . . . . . . . . . . . . . . . . . . .    20
  44.              2.2.1  How to Specify Parameters (21)
  45.          2.3  ERRORLEVEL Description . . . . . . . . . . . . . . . . . .    22
  46.  
  47.      3.  DETAILED COMMAND SUMMARY  . . . . . . . . . . . . . . . . . . .    24
  48.          ADD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  49.          ADDSLASH  . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  50.          ALARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  51.          AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    25
  52.          APPEND  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    26
  53.          APPENDS . . . . . . . . . . . . . . . . . . . . . . . . . . . .    27
  54.          APPENDSNC . . . . . . . . . . . . . . . . . . . . . . . . . . .    27
  55.          ASSIGN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    28
  56.          BEEP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    29
  57.          BOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    30
  58.          BOXGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . .    31
  59.          CADDREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    34
  60.          CAPCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    35
  61.          CAPPAUSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    36
  62.          CAPSTAMP  . . . . . . . . . . . . . . . . . . . . . . . . . . .    36
  63.          CAPPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .    37
  64.  
  65.  
  66.  
  67.  
  68.      Intellicomm v2.01               SCRIPT.DOC                             ii
  69.      
  70.      
  71.  
  72.          CAPPOP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    37
  73.          CAPTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . .    38
  74.          CCLEARBUF . . . . . . . . . . . . . . . . . . . . . . . . . . .    40
  75.          CCLEARDESC  . . . . . . . . . . . . . . . . . . . . . . . . . .    40
  76.          CCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    41
  77.          CDATE2DATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    41
  78.          CDATEDIFF . . . . . . . . . . . . . . . . . . . . . . . . . . .    42
  79.          CDELREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    43
  80.          CEDITREC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    44
  81.          CEMPTY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    45
  82.          CEXPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . .    45
  83.          CFLUSH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    47
  84.          CFORMATDESC . . . . . . . . . . . . . . . . . . . . . . . . . .    47
  85.          CGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    48
  86.          CGETDESC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    50
  87.          CGETREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    51
  88.          CGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    52
  89.          CHAT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    52
  90.          CHECKVERSION  . . . . . . . . . . . . . . . . . . . . . . . . .    53
  91.          CHDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    54
  92.          CIMPORTNEW  . . . . . . . . . . . . . . . . . . . . . . . . . .    54
  93.          CIMPORTTEXT . . . . . . . . . . . . . . . . . . . . . . . . . .    55
  94.          CLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    56
  95.          CNOTEREC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    56
  96.          COPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    57
  97.          COPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    59
  98.          CPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    60
  99.          CPURGE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    61
  100.          CPUTDESC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    61
  101.          CPUTREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    63
  102.          CSAVEBMARK  . . . . . . . . . . . . . . . . . . . . . . . . . .    63
  103.          CSAVEVDATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    64
  104.          CSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    65
  105.          CSETSORT  . . . . . . . . . . . . . . . . . . . . . . . . . . .    66
  106.          CTAGALL . . . . . . . . . . . . . . . . . . . . . . . . . . . .    66
  107.          CTAGREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    67
  108.          CTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    68
  109.          CURSORLARGE . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  110.          CURSORSMALL . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  111.          CURSOROFF . . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  112.          CURSORON  . . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  113.          CURSORPOP . . . . . . . . . . . . . . . . . . . . . . . . . . .    70
  114.          CURSORPUSH  . . . . . . . . . . . . . . . . . . . . . . . . . .    70
  115.          DATE2CDATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    71
  116.          DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    72
  117.          DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    72
  118.          DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    73
  119.          DELAYNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    73
  120.          DEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    74
  121.          DELETE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    74
  122.          DIAL  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    75
  123.          DIREXIST  . . . . . . . . . . . . . . . . . . . . . . . . . . .    77
  124.          DISKFIND  . . . . . . . . . . . . . . . . . . . . . . . . . . .    78
  125.          DISKFREE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    79
  126.          DIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    79
  127.          DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    79
  128.          DOWNLOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . .    81
  129.          EDIT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    82
  130.  
  131.  
  132.  
  133.  
  134.      Intellicomm v2.01               SCRIPT.DOC                            iii
  135.      
  136.      
  137.  
  138.          ERASELINE . . . . . . . . . . . . . . . . . . . . . . . . . . .    83
  139.          EXEC  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    83
  140.          EXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    85
  141.          EXIT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    86
  142.          FCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    87
  143.          FFLUSH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    87
  144.          FGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    88
  145.          FILEMAN . . . . . . . . . . . . . . . . . . . . . . . . . . . .    89
  146.          FILESIZE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    90
  147.          FINDFIRST . . . . . . . . . . . . . . . . . . . . . . . . . . .    90
  148.          FINDNEXT  . . . . . . . . . . . . . . . . . . . . . . . . . . .    92
  149.          FNSTRIP . . . . . . . . . . . . . . . . . . . . . . . . . . . .    93
  150.          FOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    93
  151.          FPUTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    96
  152.          FPUTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    96
  153.          FPUTSNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    97
  154.          FSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    98
  155.          FTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    99
  156.          GETENV  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    99
  157.          GETFNAME  . . . . . . . . . . . . . . . . . . . . . . . . . . .   100
  158.          GETS  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   102
  159.          GETSXY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   102
  160.          GOSUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   103
  161.          RETURN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   103
  162.          GOTO  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   104
  163.          GOTOXY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   105
  164.          HANGUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   106
  165.          HELP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   106
  166.          HELPFIND  . . . . . . . . . . . . . . . . . . . . . . . . . . .   107
  167.          IF  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   108
  168.           ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   108
  169.           ENDIF  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   108
  170.          INC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   111
  171.          INITMODEM . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  172.          INKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  173.          INKEYT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  174.          INKEYW  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  175.          KBFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   114
  176.          LIST  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   115
  177.          LOADBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   116
  178.          LOADINI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   116
  179.          LOCATEFILE  . . . . . . . . . . . . . . . . . . . . . . . . . .   117
  180.          LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   118
  181.          LOGCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   118
  182.          MENUBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   118
  183.          MENUBOXH  . . . . . . . . . . . . . . . . . . . . . . . . . . .   119
  184.          MENUBOXV  . . . . . . . . . . . . . . . . . . . . . . . . . . .   121
  185.          MENUDEFINE  . . . . . . . . . . . . . . . . . . . . . . . . . .   122
  186.          MENUHLP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   123
  187.          MENUITEMSTAT  . . . . . . . . . . . . . . . . . . . . . . . . .   124
  188.          MKDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   124
  189.          MSGOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . .   125
  190.          MSGCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   125
  191.          MSGWIND . . . . . . . . . . . . . . . . . . . . . . . . . . . .   126
  192.  
  193.  
  194.  
  195.  
  196.      Intellicomm v2.01               SCRIPT.DOC                             iv
  197.      
  198.      
  199.  
  200.          MUL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   126
  201.          NEWAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . .   127
  202.          NOTEXIST  . . . . . . . . . . . . . . . . . . . . . . . . . . .   129
  203.          OFFLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . .   129
  204.          ONLINE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   130
  205.          OR  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   130
  206.          PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   131
  207.          PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   131
  208.          PRINTNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .   133
  209.          PRINTRAW  . . . . . . . . . . . . . . . . . . . . . . . . . . .   134
  210.          PORT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   134
  211.          REDIAL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   135
  212.          RELOADSCRIPT  . . . . . . . . . . . . . . . . . . . . . . . . .   137
  213.          RENAME  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   138
  214.          RENUMBER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   138
  215.          RETURN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   139
  216.          RMDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   140
  217.          RXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   140
  218.          SAVEBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   141
  219.          SAVEINI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   142
  220.          SCAPTURE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   143
  221.          SCREENBLANK . . . . . . . . . . . . . . . . . . . . . . . . . .   143
  222.          SCREENRESTORE . . . . . . . . . . . . . . . . . . . . . . . . .   143
  223.          SCRIPT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   144
  224.          SCROLL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   145
  225.          SCROLLBACK  . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  226.          SEND  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  227.          SENDNC  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  228.          SENDNCP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  229.          SENDNP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  230.          SENDBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   148
  231.          SENDKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . .   149
  232.          SENDBREAK . . . . . . . . . . . . . . . . . . . . . . . . . . .   151
  233.          SETENV  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   153
  234.          SETCOMM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   153
  235.          SHL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   155
  236.          SHOWWHENS . . . . . . . . . . . . . . . . . . . . . . . . . . .   155
  237.          SHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   156
  238.          STAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   156
  239.          STRBLANK  . . . . . . . . . . . . . . . . . . . . . . . . . . .   157
  240.          STRCHR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   157
  241.          STRCHRI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   157
  242.          STRCPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   158
  243.          STRDEL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   159
  244.          STRINS  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   160
  245.          STRIPSLASH  . . . . . . . . . . . . . . . . . . . . . . . . . .   160
  246.          STRITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   161
  247.          STRLEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   162
  248.          STRLOWER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   163
  249.          STRCAT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   163
  250.          STRPAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   164
  251.          STRPADL . . . . . . . . . . . . . . . . . . . . . . . . . . . .   164
  252.          STRSET  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   165
  253.          STRPOS  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   166
  254.  
  255.  
  256.  
  257.  
  258.      Intellicomm v2.01               SCRIPT.DOC                              v
  259.      
  260.      
  261.  
  262.          STRRCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   167
  263.          STRRCHRI  . . . . . . . . . . . . . . . . . . . . . . . . . . .   167
  264.          STRREPLACE  . . . . . . . . . . . . . . . . . . . . . . . . . .   168
  265.          STRSTRIP  . . . . . . . . . . . . . . . . . . . . . . . . . . .   168
  266.          STRBTRIM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  267.          STRLTRIM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  268.          STRTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  269.          STRUPPER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   170
  270.          SUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   170
  271.          SUBSTR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  272.          SWITCH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  273.           CASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  274.           ENDCASE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  275.           DEFAULT  . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  276.           ENDSWITCH  . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  277.          SYSTEM  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   173
  278.          TAGGER  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   174
  279.          TERMINAL  . . . . . . . . . . . . . . . . . . . . . . . . . . .   174
  280.          TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   176
  281.          TIMERTOTAL  . . . . . . . . . . . . . . . . . . . . . . . . . .   177
  282.          TIMEUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   177
  283.          TONE  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   178
  284.          TXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   179
  285.          UPDATEDNDX  . . . . . . . . . . . . . . . . . . . . . . . . . .   179
  286.          UPLOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   179
  287.          VARIABLE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   181
  288.          VPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   181
  289.          VGETCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   183
  290.          VGETCHRS  . . . . . . . . . . . . . . . . . . . . . . . . . . .   183
  291.          VPOP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   185
  292.          WAITFOR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   185
  293.          WAITUNTIL . . . . . . . . . . . . . . . . . . . . . . . . . . .   187
  294.          WHEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   187
  295.          WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  296.           BREAK  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  297.           CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  298.           ENDWHILE . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  299.          WINDOW  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   191
  300.          WNDCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   192
  301.          WNDOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . .   192
  302.          XOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   193
  303.  
  304.      A.  SYSTEM VARIABLES  . . . . . . . . . . . . . . . . . . . . . . .   195
  305.          A.1  Introduction . . . . . . . . . . . . . . . . . . . . . . .   195
  306.               A.1.1  BIF and INI (main setup) Variables  (195); A.1.2 
  307.               Changing System Variables (195); A.1.3  READ ONLY System
  308.               Variables (196)
  309.          A.2  System Variable Summary  . . . . . . . . . . . . . . . . .   197
  310.          $ALARMS . . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  311.          $BAR_COLOR  . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  312.          $BBS_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  313.          $BETA_VERSION . . . . . . . . . . . . . . . . . . . . . . . . .   197
  314.          $BIF_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  315.          $BIF_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  316.  
  317.  
  318.  
  319.  
  320.      Intellicomm v2.01               SCRIPT.DOC                             vi
  321.      
  322.      
  323.  
  324.          $BOLD_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  325.          $BORDER_COLOR . . . . . . . . . . . . . . . . . . . . . . . . .   198
  326.          $BSSWAP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  327.          $CAP_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  328.          $CAP_STAT . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  329.          $CAREA_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  330.          $CARRIER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  331.          $CAT_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  332.          $CAT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  333.          $CCDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  334.          $CDAY_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  335.          $CFDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  336.          $CFLAG_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  337.          $CLOC_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  338.          $CNAME_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  339.          $COM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  340.          $CPRIORITY_FLD  . . . . . . . . . . . . . . . . . . . . . . . .   200
  341.          $COM_SPEED  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  342.          $CREC_STAT  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  343.          $CSIZE_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  344.          $CSORT_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  345.          $CSORT_ORDER  . . . . . . . . . . . . . . . . . . . . . . . . .   201
  346.          $CTAG_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  347.          $CTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  348.          $CVTOTAL  . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  349.          $CURDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  350.          $CURDRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  351.          $DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  352.          $DAY  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  353.          $DL_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  354.          $DL_PROTOCOL  . . . . . . . . . . . . . . . . . . . . . . . . .   202
  355.          $DOORWAY  . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  356.          $DOW  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  357.          $DSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  358.          $ECHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  359.          $ERRORLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  360.          $FARCH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  361.          $FDATE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  362.          $FDAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  363.          $FHIDDEN  . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  364.          $FHOUR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  365.          $FMIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  366.          $FMONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  367.          $FRDONLY  . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  368.          $FSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  369.          $FSIZE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  370.          $FSUBDIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  371.          $FSYSTEM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  372.          $FTIME  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  373.          $FVOLID . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  374.          $FULL_SCRIPT_NAME . . . . . . . . . . . . . . . . . . . . . . .   204
  375.          $FYEAR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  376.          $HOME_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  377.          $HOTKEY_1 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  378.  
  379.  
  380.  
  381.  
  382.      Intellicomm v2.01               SCRIPT.DOC                            vii
  383.      
  384.      
  385.  
  386.          $HOTKEY_2 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  387.          $HOTKEY_3 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  388.          $HOTKEY_4 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  389.          $HOTKEY_5 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  390.          $HOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  391.          $HSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  392.          $INI_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  393.          $KEY_ALTQ . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  394.          $KEY_CHECK  . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  395.          $KEY_FILTER . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  396.          $LINEFEED . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  397.          $LST_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  398.          $MAJOR_VERSION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  399.          $MENUSELECTION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  400.          $MIN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  401.          $MINOR_VERSION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  402.          $MONTH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  403.          $MSG_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  404.          $MSG_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . .   207
  405.          $NORM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  406.          $PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  407.          $OPSYSTYPE  . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  408.          $PRN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  409.          $REP_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  410.          $REP_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . .   208
  411.          $RXCNT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  412.          $SCRIPT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  413.          $SCRIPT_NAME  . . . . . . . . . . . . . . . . . . . . . . . . .   208
  414.          $SCRN_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  415.          $SCRN_HEIGHT  . . . . . . . . . . . . . . . . . . . . . . . . .   208
  416.          $SCRN_WIDTH . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  417.          $SCRN_WRAP  . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  418.          $SCRN_X . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  419.          $SCRN_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  420.          $SEC  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  421.          $SEND_CR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  422.          $SOUND  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  423.          $STAT_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  424.          $STAT_ON  . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  425.          $TERM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  426.          $TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  427.          $TSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  428.          $TXCNT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  429.          $UL_PATH  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  430.          $UL_PROTOCOL  . . . . . . . . . . . . . . . . . . . . . . . . .   211
  431.          $VIEW_DATE  . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  432.          $WND_BTM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  433.          $WND_HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  434.          $WND_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  435.          $WND_RIGHT  . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  436.          $WND_TOP  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  437.          $WND_WIDTH  . . . . . . . . . . . . . . . . . . . . . . . . . .   212
  438.          $YEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   212
  439.  
  440.  
  441.  
  442.  
  443.      Intellicomm v2.01               SCRIPT.DOC                           viii
  444.      
  445.      
  446.  
  447.      B.  BIF VARIABLES (Advanced Users Only) . . . . . . . . . . . . . .   213
  448.  
  449.      C.  MAIN SETUP VARIABLES (Advanced Users Only)  . . . . . . . . . .   216
  450.  
  451.      D.  COLOR CODES . . . . . . . . . . . . . . . . . . . . . . . . . .   224
  452.          D.1  Using Color Variables  . . . . . . . . . . . . . . . . . .   225
  453.  
  454.      E.  ASCII CODES . . . . . . . . . . . . . . . . . . . . . . . . . .   225
  455.          E.1  How to Use the ASCII Table . . . . . . . . . . . . . . . .   226
  456.  
  457.      F.  KEYBOARD CODES  . . . . . . . . . . . . . . . . . . . . . . . .   228
  458.          F.1  How to use the Keyboard Codes  . . . . . . . . . . . . . .   228
  459.          F.2  Example of Usage . . . . . . . . . . . . . . . . . . . . .   229
  460.  
  461.      G.  SCRIPT ERROR MESSAGES/SOLUTIONS . . . . . . . . . . . . . . . .   233
  462.  
  463.      H.  SCRIPT MEMORY LIMITS  . . . . . . . . . . . . . . . . . . . . .   238
  464.          H.1  Developing Large Scripts . . . . . . . . . . . . . . . . .   238
  465.  
  466.      I.  CREATING SCRIPTS FOR PUBLIC DISTRIBUTION  . . . . . . . . . . .   239
  467.  
  468.      J.  CHANGES FROM THE V1.00 SCRIPT LANGUAGE  . . . . . . . . . . . .   241
  469.          J.1  Version 2 Syntax Changes . . . . . . . . . . . . . . . . .   241
  470.          J.2  Version 2 Command Changes  . . . . . . . . . . . . . . . .   241
  471.          J.3  Icom v1.00 Script Conversion . . . . . . . . . . . . . . .   243
  472.  
  473.  
  474.  
  475.  
  476.      Intellicomm v2.01               SCRIPT.DOC                              1
  477.      
  478.      
  479.  
  480.                           1.  SCRIPT COMMANDS AT A GLANCE
  481.  
  482.      1.1  Introduction
  483.  
  484.      This section contains a short description of all the commands available
  485.      in the Intellicomm script language, grouped by command type/purpose.  Use
  486.      this section to locate the command you need, then look up the command in
  487.      the DETAILED COMMAND SUMMARY (which is sorted alphabetically, by script
  488.      command) for detailed explanations and examples.  If you're viewing this
  489.      document in the Icom File Viewer, you can quickly locate the Detailed
  490.      Summary of a command by pressing [Alt-F] (Find), entering the command of
  491.      interest followed by an underscore (PRINT_) then searching DOWNWARDS. 
  492.      Each command in the Detailed Summary is followed by a line of underscores
  493.      to allow you to locate a specific detailed command summary quickly.
  494.  
  495.      Items beginning with a dollar sign ($) below are not script commands, but
  496.      rather are "System Variables" which can be used with other commands in
  497.      the same way that constant paremeters are used (e.g. SEND $PASSWORD, as
  498.      was used in the introduction of SCRTUTOR.DOC).  Some System Variables are
  499.      "read only" (for informational purposes) and some are "read/write" (you
  500.      can assign other values to them to change the way Icom works).  The
  501.      System Variables are described in detail in the SYSTEM VARIABLES Appendix
  502.      following the command summaries.  Again, each System Variable in the
  503.      Detailed Summary is followed by a line of underscores to allow you to
  504.      find the Detailed Summary quickly.
  505.  
  506.      It is not advised that you attempt to memorize anything below.  The idea
  507.      is to just give this section a quick browse every once and a while until
  508.      you're generally familiar with what is available -- so you'll know what
  509.      commands (and what type of commands) exist when a need arises later.
  510.  
  511.      Immediately skip over commands/variables (or entire sections) you don't
  512.      anticipate having a need for.... The list is long, and it's important
  513.      that you make it right through the list, at least once.  Keep in mind
  514.      that most script writers will only need about 10% of the script commands
  515.      -- don't concern yourself with what you don't anticipate needing.
  516.  
  517.      1.2  Video (Screen) and Cursor Commands
  518.  
  519.      BOX           displays a box (with border and optional title) on the
  520.                    video display.
  521.      CLS           clears the terminal screen or current WINDOW to a specific
  522.                    color, or to the current screen color ($SCRN_COLOR).
  523.      CURSORLARGE   makes the cursor large (half character height).
  524.      CURSORSMALL   makes the cursor small (underline).
  525.      CURSORON      displays the screen cursor, if hidden.
  526.      CURSORONOFF   turns the cursor on or off.  This command (as opposed to
  527.                    CURSORON/CURSOROFF) is intended to be used with a variable
  528.                    ('CURSORONOFF stat' or the like, where 'stat' is a variable
  529.                    holding either 0 or 1).
  530.      CURSOROFF     hides the screen cursor.
  531.      CURSORPUSH    saves the current cursor size, location, and on/off status
  532.                    for later use with CURSORPOP.
  533.      CURSORPOP     restores the cursor to the size, location and on/off status
  534.  
  535.  
  536.  
  537.  
  538.      Intellicomm v2.01               SCRIPT.DOC                              2
  539.      
  540.      
  541.  
  542.                    it had when CURSORPUSH was last called.
  543.      ERASELINE     clears a given screen line (row) to a given color, does not
  544.                    move the cursor (use GOTOXY after ERASELINE to move the
  545.                    cursor to the blank line, if desired).
  546.      GOTOXY        moves the screen cursor to specific X/Y coordinates
  547.                    relative to the top corner of the current WINDOW.
  548.      MSGOPEN       displays a message in a centered box on the screen.
  549.      MSGCLOSE      closes the message box opened with MSGOPEN.
  550.      MSGWIND       displays a message in a box, pauses, closes the message
  551.                    box.
  552.      PRINT         displays text in the current video WINDOW using the current
  553.                    $SCRN_COLOR color, adds a CR/LF (which moves the cursor to
  554.                    the beginning of the next line).
  555.      PRINTNC       displays text in the current video WINDOW using the current
  556.                    $SCRN_COLOR color.  Similar to PRINT, but doesn't add a
  557.                    CR/LF (NC stands for 'N'o 'C'arriage return).
  558.      PRINTRAW      writes directly to the video display (ignoring the current
  559.                    WINDOW), using a specific color.  Much faster than
  560.                    PRINT/PRINTNC or PAUSE.
  561.      SCREENBLANK   activates the Icom screen blanker, if the user has screen
  562.                    blanking activated in the Icom main setup.  Screen blanking
  563.                    is done by Icom automatically even when a script is running
  564.                    (as long as $KEY_CHECK is turned on), but if you want to
  565.                    force the screen to blank at some point, before waiting for
  566.                    the usual timeout, you can use this command.
  567.      SCREENRESTORE restores the screen, if blanked.  Again, Icom automatically
  568.                    unblanks the screen by itself in most cases, when your
  569.                    script does something that the user must participate in
  570.                    (such as operating a menu, or getting input, etc).  But you
  571.                    can always ensure that the screen is not blanked with this
  572.                    command if need be, before important operations.
  573.      SCROLL        scrolls a given area of the video screen up or down, or
  574.                    clears an area to a specific color.
  575.      VGETCHR       gets the video screen character at the current cursor
  576.                    position, stores it in a variable.
  577.      VGETCHRS      gets a given number of characters from the video screen (at
  578.                    specific x/y coordinates) and stores them in a variable.
  579.      VPUSH         saves an area of the screen (or the whole screen),
  580.                    including color data, for later use with VPOP.
  581.      VPOP          restores the screen saved by the last VPUSH.
  582.      WINDOW        defines a new screen window (given screen x1/y1, x2,y2
  583.                    coordinates) or restores the terminal to full-screen if no
  584.                    coordinates are specified.  Data from the modem, and text
  585.                    you print with the PRINT, PRINTNC, and PAUSE commands will
  586.                    stay within the current WINDOW coordinates.
  587.      WNDOPEN       opens a display window (box) on the screen, saving all
  588.                    screen attributes.  A simple call to WNDCLOSE puts
  589.                    everything back the way it was.
  590.      WNDCLOSE      Removes from the video display the last window opened with
  591.                    WNDOPEN.
  592.      $BAR_COLOR    the color defined in the Icom main setup for menu hilight
  593.                    bars.
  594.      $BOLD_COLOR   'hotkeys' color (menus) and bold text color.
  595.      $BORDER_COLOR color used for box borders.
  596.  
  597.  
  598.  
  599.  
  600.      Intellicomm v2.01               SCRIPT.DOC                              3
  601.      
  602.      
  603.  
  604.      $NORM_COLOR   color used for regular text in boxes/menus.
  605.      $SCRN_COLOR   the CURRENT terminal screen color (at the positon of the
  606.                    cursor).  NOTE: BBS ANSI codes can change $SCRN_COLOR.
  607.      $SCRN_HEIGHT  total number of rows (top to bottom) on the real screen,
  608.                    ignoring the current WINDOW.
  609.      $SCRN_WIDTH   total number of columns (left to right) on the real screen,
  610.                    ignoring the current WINDOW.
  611.      $SCRN_WRAP    if non-zero, lines within the current WINDOW (or terminal
  612.                    screen) are wrapped to the next screen line when they reach
  613.                    the end of the window.  If zero, lines are truncated (cut)
  614.                    when they reach the end of the window.  NOTE: BBS ANSI
  615.                    codes can change the status of $SCRN_WRAP.
  616.      $SCRN_X       current column (x position) of the screen cursor.
  617.      $SCRN_Y       current row (y position) of the screen cursor.  NOTE: BBS
  618.                    ANSI codes can change the $SCRN_X and $SCRN_Y positions.
  619.      $STAT_COLOR   status line color.
  620.      $STAT_ON      reports the state of the status line (off is 0, on is 1)
  621.                    and allows you to turn it on and off (ASSIGN $STAT_ON 0
  622.                    turns it off, ASSIGN $STAT_ON 1 turns it on).
  623.      $TERM_COLOR   the DEFAULT terminal screen color, as defined in the Icom
  624.                    main setup.  After BBS ANSI codes have changed your screen
  625.                    color, ASSIGN $SCRN_COLOR $TERM_COLOR to set it back to the
  626.                    default color.
  627.      $WND_TOP      the top screen line of the current WINDOW.
  628.      $WND_BTM      the bottom screen line of the current WINDOW.
  629.      $WND_LEFT     the left screen row of the current WINDOW. 
  630.      $WND_RIGHT    the right screen row of the curren WINDOW.
  631.      $WND_WIDTH    the width (number of screen columns available left to
  632.                    right) of the current screen WINDOW.
  633.      $WND_HEIGHT   the height (number of screen rows available top to bottom)
  634.                    of the current screen WINDOW.
  635.  
  636.      1.3  Menu Handling
  637.  
  638.      MENUBAR      displays the currently defined menu, in 'bar menu' format.
  639.      MENUBOXH     displays the currently defined menu in 'box menu' format. 
  640.                   Menu items are displayed Horizontally in the box.
  641.      MENUBOXV     displays the currently defined menu in 'box menu' format. 
  642.                   Menu items are displayed Vertically in the box.
  643.      MENUDEFINE   define a menu for use by MENUBAR, MENUBOXH, MENUBOXV.
  644.      MENUITEMSTAT hide, disable, or unhide/enable one given menu item, in the
  645.                   currently defined menu.
  646.      MENUHLP      attaches a line of help to a given menu item.  On horizontal
  647.                   menus (MENUBAR or MENUBOXH) the help line is displayed under
  648.                   the first menu item as in the Icom Job Directory and BBS
  649.                   Directory bottom menus (when you press [Left] or [Right] the
  650.                   help line changes to the selected item).  On vertical menus
  651.                   (MENUBOXV) the help line is displayed on the bottom screen
  652.                   line.
  653.      $MENUSELECTION is set to the menu item number selected by the user (or 0
  654.                     if [Esc] is pressed) after MENUBAR, MENUBOXH or MENUBOXV.
  655.  
  656.  
  657.  
  658.  
  659.      Intellicomm v2.01               SCRIPT.DOC                              4
  660.      
  661.      
  662.  
  663.      1.4  Keyboard Input and Output
  664.  
  665.      BOXGETS     displays a box centered on the screen, with optional box
  666.                  title and information line, offers an optional 'default' to
  667.                  the user then gets input (a given number or characters) from
  668.                  the keyboard allowing use of several editing keys ([Del],
  669.                  [Ins], [Left], [Right], [Home], [End], etc) to edit the
  670.                  input.
  671.      GETS        offers an optional default and gets a line of text of a given
  672.                  length from the keyboard.  Similar to BOXGETS, but GETS
  673.                  doesn't display a box.  The [Enter] or [Esc] key, or
  674.                  left/right mouse button which signify Enter and Esc, must be
  675.                  pressed to terminate both BOXGETS and GETS.
  676.      GETSXY      same as GETS above, but GETSXY gets text at a specific screen
  677.                  X,Y coordinate.
  678.      INKEY       gets a single keystroke from the keyboard (any key; Alt-keys,
  679.                  Function keys, regular keys, etc) and stores the value of the
  680.                  key in a variable.  See the KEYBOARD CODES appendix for key
  681.                  values.  This command doesn't WAIT for a keystroke; it simply
  682.                  checks for one and stores it if one is waiting.  You'd use
  683.                  this one in a WHILE 'loop', if you wanted to do something
  684.                  while waiting for a keystroke... such as updating a clock, or
  685.                  counting something, etc.  Use INKEYW to halt script execution
  686.                  and wait for a single keypress.
  687.      INKEYT      same as INKEY above, but INKEYT waits a specified 'Timeout'
  688.                  period for a key to be pressed, and gives up if no keys are
  689.                  pressed in time.
  690.      INKEYW      same as INKEY above, but waits until a key is pressed. 
  691.                  Similar to the PAUSE command but INKEYW (and INKEY) stores
  692.                  the key code of the key pressed (i.e. you can check it to see
  693.                  what the user entered) in a given variable.
  694.      PAUSE       displays an optional message, then pauses for a keystroke
  695.                  from the user.  The key pressed is discarded.
  696.      SENDKEY     sends (simulates) one or more specific keystrokes to the Icom
  697.                  terminal key handler.  Depending on the key(s) you send, this
  698.                  may pop up an Icom menu and select something, or may be sent
  699.                  to the BBS -- whatever would happen if you pressed the key
  700.                  from Terminal mode.  If "Doorway Mode" is on, ALL keys other
  701.                  than [Alt-=] (doorway mode on/off) are sent to the BBS.
  702.      $DOORWAY    the current status of 'Doorway Mode'.  0 = Off, 1 = On.  If
  703.                  $DOORWAY is ON (non-zero), the regular Icom hotkeys ([Alt-Z]
  704.                  to pop up the terminal menu, etc) are sent to the BBS instead
  705.                  of performing their usual function.  Doorway mode is only of
  706.                  use only when $KEY_CHECK (see below) is non-zero, and only
  707.                  with a BBS function or BBS DOOR that supports doorway codes
  708.                  and recognizes the extended key codes.  Doorway codes are
  709.                  often supported in online information systems (online
  710.                  encyclopedias, etc) to allow a more advanced user interface
  711.                  with function keys and support for the [Alt] keys, etc.
  712.      $HOTKEY_?   the ? must be replaced with a number from 1 through 5
  713.                  ($HOTKEY_1, $HOTKEY_2 ... to $HOTKEY_5).  These hotkeys, if
  714.                  defined, are watched for by BOXGETS, GETS, and GETSXY to
  715.                  allow you to cancel input when specific keys are pressed
  716.                  WHILE the user is entering something in the input field.  For
  717.  
  718.  
  719.  
  720.  
  721.      Intellicomm v2.01               SCRIPT.DOC                              5
  722.      
  723.      
  724.  
  725.                  example, the input box Intellicomm displays when prompting
  726.                  for filenames to UPLOAD allows the user to press the [Alt-F]
  727.                  key to display the 'file picker' instead of entering
  728.                  filenames manually.  You can do similar things with your own
  729.                  BOXGETS/GETS/GETSXY input prompts by using the $HOTKEY_?
  730.                  variables.  See the KEYBOARD CODES appendix for a list of
  731.                  extended keys you can ASSIGN to these hotkeys.  Also see the
  732.                  BOXGETS detailed summary for an example of usage.
  733.      $KEY_CHECK  this goes one step further than $DOORWAY, and determines
  734.                  whether ANY keys will be processed by Intellicomm at all.  If
  735.                  $KEY_CHECK is set to zero (0), it's up to you to use INKEY or
  736.                  INKEYW to process ALL user keystrokes (please see the notes
  737.                  in $KEY_ALTQ below).  $KEY_CHECK is automatically turned back
  738.                  on (set to 1) when the script processor exits.
  739.      $KEY_FILTER similar to the $HOTKEY_? variables, this is used with
  740.                  GETS/GETSXY and BOXGETS but the characters defined in
  741.                  $KEY_FILTER (if any) are NOT accepted in input fields.  For
  742.                  example, if you were getting a filename you might put a space
  743.                  in the $KEY_FILTER using ASSIGN $KEY_FILTER " " which would
  744.                  prevent the user from entering a space during the next
  745.                  BOXGETS/GETS/GETSXY command.  You can define up to ten
  746.                  characters to ignore... ASSIGN $KEY_FILTER "*? " would
  747.                  prevent the user from entering asterisks, question marks and
  748.                  spaces in the input field.  All characters assigned to
  749.                  $KEY_FILTER must be regular ASCII characters.  To filter out
  750.                  control characters, use the caret ("^[" is ESC, "^C" is Ctrl-
  751.                  C, etc).  See ASCII CODES in the Appendix for control
  752.                  characters.
  753.      $KEY_ALTQ   if non-zero, Icom checks for [Alt-Q] (abort job or script,
  754.                  turn on script debugging, etc) while your script is running. 
  755.                  If you want to prevent the user from aborting the script,
  756.                  ASSIGN $KEY_ALTQ 0 (set it to 0) and Icom will not pop up the
  757.                  Control Menu when Alt-Q is pressed.  This should only be used
  758.                  when you have something to clean up when your script ends,
  759.                  such as resetting System Variables or re-loading a BIF or
  760.                  main setup file, etc.  If you shut this off, you should
  761.                  substitute your own script abort menu by checking for Alt-Q
  762.                  (key code 4096) after INKEY, INKEYW and/or setting a
  763.                  $HOTKEY_? to Alt-Q (ASSIGN $HOTKEY_1 4096) for BOXGETS,
  764.                  GETS/GETSXY to observe.  The best way to handle it is by
  765.                  using a subroutine (GOSUB MY_INKEY, GOSUB MY_INKEYW, GOSUB
  766.                  MY_BOXGETS, etc.) to get keys, then check for Alt-Q (4096) in
  767.                  the subroutine.  If the user enters Alt-Q Pop up an "Abort
  768.                  script?  Yes  No" menu with BOXMENUH.  If Yes is selected,
  769.                  call your 'clean_up' subroutine to reset whatever needs
  770.                  resetting, then EXIT.
  771.  
  772.      1.5  Communications
  773.  
  774.      CAPTURE    closes current capture, if open, then opens a new capture
  775.                 file.
  776.      CAPCLOSE   closes the current capture file, doesn't open a new one.
  777.      CAPPUSH    saves the current capture D:\PATH\FILENAME.EXT, and status
  778.                 (open, closed, paused), for later use with CAPPOP.  CAPPUSH
  779.  
  780.  
  781.  
  782.  
  783.      Intellicomm v2.01               SCRIPT.DOC                              6
  784.      
  785.      
  786.  
  787.                 saves the capture filename/status only ONCE.  If you call it
  788.                 again before using CAPPOP, you lose the previous CAPPUSH data.
  789.      CAPPOP     restores the capture filename and status (open/closed/paused)
  790.                 to the value they had when CAPPUSH was last called.
  791.      CAPSTAMP   stamps a line in the capture file (if open) containing the
  792.                 current date, time, BIF ID and BBS/Host Name.
  793.      CGETC      gets a character from the current COM port and stores it in a
  794.                 variable.  If no characters are available, CGETC waits until a
  795.                 specified timeout has elapsed (or indefinitely if no timeout
  796.                 is given).
  797.      CGETS      gets a 'string' of characters from the COM port, and stores it
  798.                 in a specified variable.  CGETS also takes an optional 'end-
  799.                 of-string' character and timeout, and it returns control only
  800.                 after a Carriage Return (CR) is received, or the specified
  801.                 end-of-string character is received, or the timeout elapses.
  802.      DIAL       dials one or more BBS Information Files, or a specific phone #
  803.                 (similar to the "Manual" dial option in the BBS Directory), or
  804.                 displays the BBS Directory for manual user input.
  805.      DOWNLOAD   downloads one or more files using a specified protocol.
  806.      HANGUP     same as pressing [Alt-H] from Terminal mode... tells the modem
  807.                 to disconnect.
  808.      INITMODEM  same as pressing [Alt-I] from Terminal mode... sends the
  809.                 "Initialize Modem" string, defined on the main setup/Terminal
  810.                 screen, to the modem.
  811.      LOG        opens a new usage log file (the default usage log is
  812.                 \ICOM\CAP\ICOM.USE).
  813.      LOGCLOSE   closes the usage log, if open.  Once closed, Icom will not
  814.                 write usage data of any sort.
  815.      NEWAREA    uses the commands and prompts defined in the currently loaded
  816.                 BIF to change to a new area of the BBS.  You can change to the
  817.                 Main Menu, Message Menu, Bank Menu, File Menu, or change file
  818.                 areas/message areas ([J]oin a conference, etc).  If the area
  819.                 change is unsuccessful, $ERRORLEVEL is set.  There are some
  820.                 considerations for using this command properly, which are
  821.                 outlined in the DETAILED COMMAND SUMMARY.
  822.      OFFLINE    if the modem is not connected, a command is carried out.
  823.      ONLINE     if the modem IS connected, a command is carried out.
  824.      PORT       changes to another COM port (current port is closed first...
  825.                 you'll lose the connection if connected).
  826.      REDIAL     used after DIAL to re-dial any BIFs that remain tagged.  
  827.      RXBUF      tells you how many (if any) characters are waiting in the
  828.                 receive buffer.  See below.
  829.      RXFLUSH    empties the Icom receive buffer.  Characters received from the
  830.                 COM port that have not been processed yet (CGETC, CGETS, SEND,
  831.                 SENDBIF, SENDNC, WAITFOR, and TERMINAL are the only commands
  832.                 that process incoming characters from the port) will pile up
  833.                 in the receive buffer.  If you aren't expecting (or don't
  834.                 need) input from the port at a given point in your script, or
  835.                 if you want to clear any line noise before an operation, use
  836.                 RXFLUSH to get rid of garbage.
  837.      SCROLLBACK same as pressing [Alt-B] from Terminal Mode.  Enters the
  838.                 scrollback buffer.
  839.      SEND       sends text out the current COM port (to the BBS), and follows
  840.                 it with a Carriage Return (CR, same as pressing the [Enter]
  841.  
  842.  
  843.  
  844.  
  845.      Intellicomm v2.01               SCRIPT.DOC                              7
  846.      
  847.      
  848.  
  849.                 key).  If a "Response Delay" is defined in the current BIF,
  850.                 SEND delays sending of the data for the duration of the
  851.                 Response Delay.
  852.      SENDNP     SEND with No Pause.  Same as SEND above, but doesn't observe
  853.                 the BIF Response Delay.
  854.      SENDNCP    SEND No CR or Pause.  Same as SEND above, but never adds a CR,
  855.                 and doesn't observe the Response Delay,
  856.      SENDBIF    sends a specific BIF command out the current COM port, or runs
  857.                 a @SCRIPT, or executes a !DOS command, as BIF commands are
  858.                 entitled to do.  If "CR w/Commands?" on BIF screen 1 of the
  859.                 current BIF in use is set to "Yes", then a CR is added after
  860.                 the response.  Otherwise, no CR is added (BBS hotkeys), just
  861.                 as with Icom's automated routines.  SENDBIF is exactly what
  862.                 Icom uses to handle BIF responses during automated jobs.
  863.      SENDBREAK  sends a break signal to the current COM port.  On error-
  864.                 correcting modems, a break usually clears the modem transmit
  865.                 buffer (a good way to flush data after a cancelled transmit
  866.                 operation).
  867.      SENDNC     same as SEND, but doesn't add a CR.
  868.      SETCOMM    changes the current COM port settings (baud, parity, etc).
  869.      SHOWWHENS  shows the currently defined WHENs, and the command (up to 20
  870.                 characters) that will be executed WHEN the text is found. 
  871.                 Mainly for debugging BIFs and automated jobs to see which BBS
  872.                 prompts Icom is tracking during a given job.
  873.      STAMP      stamps a COMMENT record in the Usage Log, if open.
  874.      TERMINAL   is an advanced command that will only be needed if your script
  875.                 fails to display characters from the BBS and doesn't allow
  876.                 keys to be processed ([Alt-Z] to pop up the Terminal menu,
  877.                 etc). If you run into this problem, look up TERMINAL's details
  878.                 in the Detailed Command Summary.
  879.      TXBUF      tells you how many (if any) characters are waiting to be sent
  880.                 to the modem (COM port) in the transmit buffer.  See next.
  881.      TXFLUSH    clears characters waiting to be sent to the modem from the
  882.                 transmit buffer.  SEND, SENDBIF, SENDKEY, and SENDNC send
  883.                 characters to the transmit buffer.  When the modem is ready to
  884.                 send, characters are moved from the transmit buffer to the COM
  885.                 port (where the modem then takes them and sends them to the
  886.                 BBS).  Use TXFLUSH to get rid of any characters sitting in the
  887.                 transmit buffer. 
  888.      UPLOAD     uploads one or more files using a specified protocol.
  889.      WAITFOR    handles WHENs (if any) while waiting for specific text from
  890.                 the current COM port.  An optional timeout can be specified
  891.                 with an optional script label to GOTO if the text isn't found.
  892.      WHEN       defines text to watch for (and handle with a specific command,
  893.                 if found) while WAITFOR is active.  Also used to clear
  894.                 previously defined WHENs.
  895.      $BBS_AREA  is set to a letter, enclosed in square brackets, reflecting
  896.                 the current BBS Area (Main Menu, Message Menu, Bank Menu, or
  897.                 File Menu, or 'location unknown' if blank), for use mainly
  898.                 when calling scripts from automated jobs.  When your script
  899.                 starts you can check the current area by checking $BBS_AREA,
  900.                 and can move to a new area if need be with the NEWAREA
  901.                 command.  $BBS_AREA will only be set to an area if Intellicom
  902.                 was AT the main menu of the area when your script was called.
  903.  
  904.  
  905.  
  906.  
  907.      Intellicomm v2.01               SCRIPT.DOC                              8
  908.      
  909.      
  910.  
  911.      $CARRIER   the state of the DCD signal (carrier detect) on the current
  912.                 $COM_PORT.  If 0 (zero), the modem is reporting offline (not
  913.                 connected).  If non-zero the modem is reporting online
  914.                 (connected).  See "Common Questions & Answers" in the Icom
  915.                 online help for a fix if your modem isn't telling the truth
  916.                 and reports online always.
  917.      $COM_PORT  the number of the current COM port (1-8; 1 = COM1, etc).
  918.      $COM_SPEED the current speed (baud rate) of the COM port (300-115200).
  919.      $SEND_CR   a flag (zero is 'off', non-zero is 'on') that determines
  920.                 whether the SEND command adds a Carriage Return (CR; the same
  921.                 as pressing [Enter]) after the data it sends.
  922.  
  923.      1.6  Icom Information / Script Variables
  924.  
  925.      ASSIGN         assigns text or numbers to a variable.
  926.      GETENV         gets DOS environment data (PATH, PROMPT, etc) and stores
  927.                     in a variable.
  928.      SETENV         changes, sets, or clears a DOS environment variable (PATH,
  929.                     PROMPT, etc., or an environment variable you're using to
  930.                     keep track of specific information).
  931.      VARIABLE       defines a variable name and allocates storage space in
  932.                     memory.  You can also assign data to the variable when
  933.                     defining it.
  934.      $BETA_VERSION  the current beta version of Intellicomm (or 0 if a
  935.                     production release).
  936.      $BIF_DIR       the BIF directory (where .BIF files are found).
  937.      $BIF_NAME      the filename of the currently loaded BIF (no extension;
  938.                     it's always .BIF).
  939.      $CAP_NAME      the current capture file (D:\PATH\FNAME.EXT).
  940.      $CAP_STAT      the current status of the capture file (0 = closed, 1 =
  941.                     open, 2 = paused).
  942.      $CAT_DIR       the Catalog Directory (File Tagger databases) as defined
  943.                     in the Icom main setup.
  944.      $CAT_NAME      the name of the currently open Catalog (if open).
  945.      $DSEP          the 'Date Separator' character as defined in the Icom main
  946.                     setup.
  947.      $DL_DIR        the current Download Directory (BIF or main setup if no
  948.                     Download Dir defined in the BIF).
  949.      $DL_PROTOCOL   the "Receive Files" protocol, as defined in the current
  950.                     BIF.
  951.      $ERRORLEVEL    set to specific numbers by commands (see ERRORLEVEL
  952.                     sections in the Detailed Command Summary).
  953.      $FULL_SCRIPT_NAME the full D:\PATH\FILENAME.EXT of the currently
  954.                        executing script.  Also see $SCRIPT_NAME.
  955.      $HOME_DIR      the Icom home directory (where ICOM.EXE is, or where the
  956.                     ICOM environment variable points to).
  957.      $LST_DIR       Icom List Directory (main setup option defaults to
  958.                     \ICOM\LST).  This is where Icom looks for .NEW files lists
  959.                     to auto-import to the Tagger catalogs.
  960.      $MAJOR_VERSION Intellicomm major version number (2, 3, etc).
  961.      $MINOR_VERSION Intellicomm minor version number (0 1 10, etc.) after the
  962.                     decimal.  Icom v2.10 would have a $MAJOR_VERSION of 2 and
  963.                     a $MINOR_VERSION of 10 (ten).
  964.      $MSG_DIR       the current Message Directory (BIF or main setup if no BIF
  965.  
  966.  
  967.  
  968.  
  969.      Intellicomm v2.01               SCRIPT.DOC                              9
  970.      
  971.      
  972.  
  973.                     Message Dir defined).
  974.      $MSG_PROTOCOL  the "Receive Messages" protocol, as defined in the current
  975.                     BIF.
  976.      $PASSWORD      the logon password defined in the current BIF.
  977.      $PRN           the printer device defined in the main setup (defaults to
  978.                     PRN).
  979.      $REP_DIR       the current Reply Directory (BIF or main setup if no BIF
  980.                     Reply Dir defined).
  981.      $REP_PROTOCOL  the "Send Replies" protocol, as defined in the current
  982.                     BIF.
  983.      $SCRIPT_DIR    the Icom Script Directory, as defined in the main setup.
  984.      $SCRIPT_NAME   the FILENAME.EXT of the current script (no D:\PATH\ ...
  985.                     use this when simply want to print the script name for
  986.                     user consumption).
  987.      $TSEP          the 'Time Separator' character as defined in the Icom main
  988.                     setup.
  989.      $UL_PATH       the full Upload PATH (BIF or main setup if no BIF path
  990.                     Upload PATH defined).  Upload PATHs are in the format:
  991.                     D:\DIR1;D:\DIR2 etc.  Use STRITEM to obtain a specific
  992.                     directory from the path.
  993.      $UL_PROTOCOL   the "Send Files" protocol, as defined in the current BIF.
  994.  
  995.      1.7  Text (String) Handling
  996.  
  997.      ADDSLASH checks a variable containing text (usually a directory name) to
  998.               see whether it has a trailing backslash (\) or not.  If it does
  999.               have a trailing backslash, nothing is done.  If it doesn't have
  1000.               a trailing backslash, a backslash is added.  EXCEPTION: if the
  1001.               variable contains only a drive letter (C:), a slash is not
  1002.               added.
  1003.      SETCHR   puts a single character into a string, at a given point,
  1004.               overwriting the previous character.
  1005.      SETCHRS  copies one string into another, at a given point, overwriting
  1006.               the original string portion.
  1007.      STRBLANK checks to see if a variable is blank (empty or all whitespace*).
  1008.      STRCHR   finds the first occurrance of a given character in a given
  1009.               string (case sensitive) and stores the position of the character
  1010.               in a variable.  This command is most likely to be used in
  1011.               combination with another of the string handing functions, such
  1012.               as STRINS or STRDEL.
  1013.      STRCHRI  same as STRCHR, but case (UPPERCASE/lowercase) of the character
  1014.               searched for is ignored.
  1015.      STRCPY   copies one string (or a portion) to another at a given position.
  1016.      STRDEL   deletes a given number of characters from a given position in a
  1017.               variable.
  1018.      STRITEM  gets a specific item from a variable (see detailed summary).
  1019.      STRLOWER converts text in a variable to lower case.
  1020.      STRCAT   adds (concatenates) one string to the end of another.
  1021.      STRINS   inserts a given number of characters from one string to a given
  1022.               position in a variable.  STRCAT adds text only to the end of a
  1023.               variable.  Use STRINS to add text at any position.
  1024.      STRLEN   gets the length of a given constant or variable (check the
  1025.               length of a string).
  1026.      STRPAD   pads a variable (with any character) to a given length.  Pad
  1027.  
  1028.  
  1029.  
  1030.  
  1031.      Intellicomm v2.01               SCRIPT.DOC                             10
  1032.      
  1033.      
  1034.  
  1035.               characters are added to the RIGHT side of the variable.
  1036.      STRPADL  pads a variable (with any character) to a given length.  Pad
  1037.               characters are inserted on the LEFT side of the variable (useful
  1038.               for lining numbers up; right justified).
  1039.      STRSET   sets a given number of characters in a variable (at a given
  1040.               positon) to a given character.
  1041.      STRPOS   looks for a substring in another string, stores the position (if
  1042.               found) in a variable.  Case IS sensitive.
  1043.      STRPOSI  is the same as STRPOS, but case is not sensitive.
  1044.      STRRCHR  searches a given string from the last character towards the
  1045.               first, for a given character (case sensitive).
  1046.      STRRCHRI searches a given string from the last character towards the
  1047.               first, for a given character (case insensitive).
  1048.      STRREPLACE  replaces all occurrances of one string in another (case
  1049.                  sensitive).
  1050.      STRREPLACEI replaces all occurrances of one string in another (case
  1051.                  insensitive).
  1052.      STRSTRIP strip all occurrances of a given character from a given
  1053.               variable.  The character, if found, is not replaced with another
  1054.               character; text from the right is simply pulled over to
  1055.               overwrite the character until the character no longer exists in
  1056.               the string.  Use to simply eliminate unwanted characters from
  1057.               text, such as commas, spaces, etc.
  1058.      STRTRIM  trims whitespace* from the right side of a string.
  1059.      STRLTRIM trims whitespace* from the left side of a string.
  1060.      STRBTRIM trims whitespace* from both the left and right side of a string.
  1061.      STRUPPER converts text in a variable to upper case.
  1062.      SUBSTR   copies a portion of one variable to another variable.
  1063.  
  1064.      * Spaces, tabs, and Carriage Return/Line Feed characters are
  1065.        'whitespace'.  'White' because when you send these characters to a
  1066.        printer they leave white space on the paper.
  1067.  
  1068.      1.8  Math Commands
  1069.  
  1070.      ADD  adds two numbers and stores the result in a variable.
  1071.      AND  is an advanced command for programmers.  If performs a bitwise AND
  1072.           on two numbers, and stores the result in a variable.  If you don't
  1073.           know what a bitwise AND is, you won't need this command.
  1074.      DIV  divides two numbers, stores the result in a variable.
  1075.      DEC  (DECrement) subtracts 1 from the contents of a variable (x = x - 1).
  1076.      INC  (INCrement) adds 1 to the contents of a variable (x = x + 1).  INC
  1077.           and DEC are used mainly for counting.
  1078.      OR   is an advanced command for programmers, similar to the AND command
  1079.           above.  It performs a bitwise OR on two numbers and stores the
  1080.           result in a variable.  If you don't know what a bitwise OR is, you
  1081.           needn't concern yourself with this command.
  1082.      MUL  multiplies two numbers, stores the result in a variable.
  1083.      SHL  (SHift Left) is also an advanced command for programmers which
  1084.           shifts a given number of bits in a number towards the left.  The
  1085.           result is stored in a given variable.  Each bit shifted to the left
  1086.           has the effect of multiplying the original number by two (2).
  1087.      SHR  (SHift Right) is another an advanced command for programmers which
  1088.           shifts a given number of bits in another number towards the right. 
  1089.  
  1090.  
  1091.  
  1092.  
  1093.      Intellicomm v2.01               SCRIPT.DOC                             11
  1094.      
  1095.      
  1096.  
  1097.           The result is stored in a given variable.  Each bit shifted to the
  1098.           right has the effect of dividing the original number by two (2).
  1099.      SUB  subtracts one number from another, stores the result in a variable.
  1100.      XOR  is similar to AND/OR above, but performs a bitwise eXclusive OR on
  1101.           two numbers and stores the result in a variable.  This one, while
  1102.           it's also mainly for programmers, can actually be quite useful to
  1103.           non-programmers and it's worth a looksee in the Detailed Summary.
  1104.  
  1105.      1.9  DOS and File Input/Output Commands
  1106.  
  1107.      APPEND     adds the contents of one text file to the end of another text
  1108.                 file (the original file remains intact).
  1109.      APPENDS    adds one line ('S'tring; a script variable or constant) to the
  1110.                 end of a text file.  Terminates the line with a Carriage
  1111.                 Return (CR) and Line Feed (LF) and closes the file.
  1112.      APPENDSNC  same as APPENDS, but doesn't add CR/LF to terminate the line
  1113.                 (NC stands for 'N'o 'C'arriage return).
  1114.      CHDIR      changes DOS's 'current directory' (same as CHDIR from DOS).
  1115.      COPY       copies one file (text or binary) to another filename and/or
  1116.                 directory.  Overwrites files of the same destination name (use
  1117.                 APPEND to add one file to another).  Similar to the DOS 'COPY'
  1118.                 command.
  1119.      DEL/DELETE delete a file on-disk.  Similar to the DOS 'DELETE' command,
  1120.                 and wildcards (* and ?) are accepted in the filespec.  Be
  1121.                 careful with this one ... DELETE "*.*" doesn't ask you to
  1122.                 confirm before it deletes all files in the directory.
  1123.      DIRFIND    looks for a directory on-disk, executes a script command if it
  1124.                 DOES exist.  This command is similar to EXIST, but looks for a
  1125.                 directory instead of a file.
  1126.      DISKFIND   searches all directories on a given disk for a given filespec
  1127.                 (* and ? accepted).  If the file is found its full
  1128.                 drive/pathname (D:\DIR\FILENAME.EXT) is stored in a given
  1129.                 variable.
  1130.      DISKFREE   stores the amount of free disk space on a given disk in a
  1131.                 given variable.
  1132.      DOS        executes a DOS command (or runs another program or .BAT file)
  1133.                 or performs a DOS shell.
  1134.      EXEC       similar to the DOS command above, but EXEC does not use the
  1135.                 command processor (COMMAND.COM) to execute the given command. 
  1136.                 EXEC is used when you need the 'errorlevel' reported by a .COM
  1137.                 or .EXE.  Most of the COMMAND.COM features (running .BAT
  1138.                 files, executing commands such as COPY, etc) are not supported
  1139.                 by EXEC.  Simple redirections (> or >> to redirect program
  1140.                 output to a file or device) are supported by EXEC if you need
  1141.                 them, but pipes (|) and input redirection (<) are not
  1142.                 supported.  Use the 'DOS' command above for those.
  1143.      EXIST      looks for a file on-disk, executes a script command if it DOES
  1144.                 exist.  This command also sets the file attribute System
  1145.                 Variables listed below, if a file is found.
  1146.      FCLOSE     closes a file previously opened by FOPEN.
  1147.      FFLUSH     flush (write) any data in the write buffer of an open file.
  1148.      FGETC      gets one character from an open file.
  1149.      FGETS      gets one line from an open file.
  1150.      FNSTRIP    takes a given filename and removes various components (drive
  1151.  
  1152.  
  1153.  
  1154.  
  1155.      Intellicomm v2.01               SCRIPT.DOC                             12
  1156.      
  1157.      
  1158.  
  1159.                 only, drive and filename only, path only, etc).
  1160.      FILESIZE   puts the size of a file in a variable, if the file is found
  1161.                 (wildcards are accepted).  Also sets the file attribute System
  1162.                 Variables listed below.
  1163.      FINDFIRST  locates the first file matching a given filespec and set of
  1164.                 file attributes (*.SCR, *.*, hidden files, read only files,
  1165.                 subdirectories only, etc) and stores the filename in a given
  1166.                 variable.  This command also sets the file attribute System
  1167.                 Variables listed below, if a file is found.
  1168.      FINDNEXT   locates the next matching file after a FINDFIRST and stores
  1169.                 the filename in a given variable.  This command also sets the
  1170.                 file attribute System Variables listed below.
  1171.      FOPEN      opens a file for appending, reading, writing or read/write.
  1172.      FPUTC      writes a character to an open file.
  1173.      FPUTS      writes a line to an open file, following it with a Carriage
  1174.                 Return (CR) and Line Feed (LF).
  1175.      FPUTSNC    same as FPUTS but doesn't add CR/LF to the end of the line.
  1176.      FSEEK      seeks to a specific position (byte) in an open file.
  1177.      FTELL      reports the current position (byte) of an open file.
  1178.      GETFNAME   displays all files matching a given filespec, and allows the
  1179.                 user to "Select" one or more files for your script to operate
  1180.                 on.  Useful whenever you must get one or more filenames from
  1181.                 the user.
  1182.      LOCATEFILE searches the current Download Dir, Upload PATH, and the DOS
  1183.                 PATH (if "Use PATH to locate files" is turned ON in the Icom
  1184.                 main setup) to locate a given filespec (* and ? accepted).  If
  1185.                 the file is found, its full path is stored in a given
  1186.                 variable.
  1187.      MKDIR      makes a new disk directory.
  1188.      NOTEXIST   looks for a file (or filespec) on-disk, executes a script
  1189.                 command if it DOESN'T exist.  If the file does exist, this
  1190.                 command also sets all the file attribute System Variables
  1191.                 listed below.
  1192.      RENAME     rename or MOVE a file (from one directory to another) on-disk.
  1193.      RENUMBER   Renumbers a given set of files, similar to the Capture file
  1194.                 renumbering (ICOM.CAP, ICOM01.CAP, ICOM02.CAP, etc).
  1195.      RMDIR      remove (delete) an empty disk directory.
  1196.      SCAPTURE   writes (appends to, if the file exists) a snapshot of the
  1197.                 screen to a given file (or the Screen Capture file
  1198.                 \ICOM\CAP\SCREEN.CAP by default if no filename specified).  
  1199.      $CURDIR    the current DOS directory.
  1200.  
  1201.      The following System Variables are set by the EXIST, FILESIZE, FINDFIRST,
  1202.      FINDNEXT, and NOTEXIST commands, if the specified file file/filespec
  1203.      exists.  If the file doesn't exist all except $FSIZE are set to 0 ($FSIZE
  1204.      is set to -1).  Note that these variables are set to the attributes of
  1205.      the currently executing SCRIPT when a script begins.  So if you want to
  1206.      check the script size or modification date (or any other attribute) just
  1207.      access these variables at script startup, before you use EXIST, FILESIZE,
  1208.      FINDFIRST, FINDNEXT, or NOTEXIST:
  1209.  
  1210.      $FDAY     file modification date, day of month (0-31).
  1211.      $FMONTH   file modification date, month (1-12).
  1212.      $FYEAR    file modification date, full year (1993, etc).
  1213.  
  1214.  
  1215.  
  1216.  
  1217.      Intellicomm v2.01               SCRIPT.DOC                             13
  1218.      
  1219.      
  1220.  
  1221.      $FHOUR    file modification time, hour (0-23).
  1222.      $FMIN     file modification time, minute (0-59).
  1223.      $FSEC     file modification time, second (0-59).
  1224.      $FSIZE    size of the file, in bytes.
  1225.      $FRDONLY  read-only attribute (will hold + if set, - if clear).
  1226.      $FHIDDEN  hidden attribute (+ if set, - if clear).  You must use
  1227.                FINDFIRST/FINDNEXT to find hidden files.
  1228.      $FSYSTEM  'system file' attribute (+ if set, - if clear).  You must use
  1229.                FINDFIRST/FINDNEXT to find system files.
  1230.      $FVOLID   Volume ID attribute (+ if set, - if clear).  This will only be
  1231.                set on one file in the root directory.  You must use
  1232.                FINDFIRST/FINDNEXT to find the Volume ID.
  1233.      $FSUBDIR  subdirectory attribute (+ if set, - if clear).  I.e. this is
  1234.                not a file, it's the name of a subdirectory.  You must use
  1235.                FINDFIRST/FINDNEXT to find subdirectories.
  1236.      $FARCH    archive attribute (+ if set, - if clear).  If the archive
  1237.                attribute is +, the file has been changed since the last disk
  1238.                BACKUP (most backup programs clear the archive attribute after
  1239.                the file is backed up.  DOS sets it again if you modify the
  1240.                file or create a new file).
  1241.  
  1242.      1.10  Date and Time
  1243.  
  1244.      TIMER      starts a timer and sets it to expire after a given number
  1245.                 (tenths of a second).
  1246.      TIMERTOTAL the total time elapsed (in tenths of a second) since TIMER was
  1247.                 last called.
  1248.      TIMEUP     checks the timer started with TIMERSTART to see whether it has
  1249.                 expired.  If it has, the script command following TIMEUP is
  1250.                 executed.
  1251.      $DATE      the current system date in text format (MM/DD/YY or the format
  1252.                 defined by the user in the Icom main setup).
  1253.      $DAY       current day of month (1-31)
  1254.      $DOW       current day of week (1-7)
  1255.      $HOUR      current hour (0-23)
  1256.      $HSEC      current hundredth of a second (0-99)
  1257.      $MIN       current minute (0-59)
  1258.      $MONTH     current month (1-12)
  1259.      $SEC       current second (0-59)
  1260.      $TIME      the current system time in text format (HH:MM:SS or the format
  1261.                 defined by the user in the Icom main setup).
  1262.      $YEAR      current year (1993, etc.)
  1263.  
  1264.      1.11  Script Flow / Decision-Making
  1265.  
  1266.      IF        compares two items (usually one or both items being variables)
  1267.                for equality, inequality,  greater than/less than, etc.  IF has
  1268.                two incarnations.  If you specify another script command after
  1269.                the IF comparison, the specified command is executed if the
  1270.                comparison is TRUE, and is skipped if the comparison is FALSE. 
  1271.                If no command is specified after the IF comparison, it is
  1272.                assumed you are using an IF/ELSE/ENDIF sequence, which allows
  1273.                you to execute one SET of commands if the comparison is TRUE,
  1274.                and another SET of commands if the comparison is FALSE (the
  1275.  
  1276.  
  1277.  
  1278.  
  1279.      Intellicomm v2.01               SCRIPT.DOC                             14
  1280.      
  1281.      
  1282.  
  1283.                commands after the ELSE, if ELSE is used).
  1284.      CHECKVERSION takes a version number in the format "x.xx" ... or "x" ...
  1285.                or "x.x" (e.g. "2.00", "2", "2.0", etc) and compares the
  1286.                numbers to the current Intellicomm version number.  If the Icom
  1287.                version number is less than the version number (or portion of
  1288.                the version number) you specify, the script aborts with the
  1289.                error message: "Sorry, this script requires Intellicomm vx.xx
  1290.                or above." (where x.xx is the version number specified in
  1291.                CHECKVERSION).
  1292.      DELAY     pauses your script; allows incoming characters from the BBS to
  1293.                be displayed during the pause.
  1294.      DELAYNC   pauses your script; DOESN'T allow incoming characters from the
  1295.                COM port to be displayed.
  1296.      EXIT      ends the script with optional error return code.  See the
  1297.                detailed summary before using this command with an error return
  1298.                code.
  1299.      GOSUB     turns control over to a subroutine temporarily.  Similar to
  1300.                GOTO, but GOSUBs are temporary, and they RETURN control to the
  1301.                command following the GOSUB (or back to the WAITFOR if called
  1302.                from a WHEN) when they're done.  GOSUB is especially useful in
  1303.                WHEN commands to have more than one command carried out when
  1304.                BBS text is found.
  1305.      GOTO      jumps to a 'label:' without returning.
  1306.      RELOADSCRIPT reloads the current script from disk and starts running it
  1307.      at
  1308.                the beginning again.
  1309.      RETURN    returns from a subroutine, or back to the caller (whatever
  1310.                started the script) if used after a GOSUB.
  1311.      SCRIPT    runs another script then returns control to the calling script. 
  1312.                Similar to GOSUB, but runs another script as the subroutine.
  1313.      SWITCH    executes one or more script commands based on a given
  1314.      condition.
  1315.       CASE     specifies a condition.
  1316.       ENDCASE  denotes the end of one condition (mandatory).
  1317.       ENDSWITCH denotes the end of the SWITCH statement (mandatory).
  1318.      SYSTEM    exits Intellicomm (after closing the port, etc., and either
  1319.                hangup up, staying connected, or prompting whether to hang up)
  1320.                back to DOS with an optional DOS 'errorlevel'.
  1321.      WAITUNTIL displays a box on the screen showing the time and/or day to
  1322.                WAITUNTIL, along with the current date and time, and a list of
  1323.                menu options (complete with a screen blanker) then pauses the
  1324.                script until the specified time and/or day, or until the user
  1325.                aborts the pause.
  1326.      WHILE     executes a set of commands WHILE a condition remains true.
  1327.       BREAK    exits a WHILE 'loop'.
  1328.       CONTINUE jumps back to the top of a WHILE 'loop' (check condition
  1329.      again).
  1330.       ENDWHILE denotes the end of the WHILE loop (mandatory).
  1331.  
  1332.      1.12  Other Useful Commands
  1333.  
  1334.      ALARM    sounds an alarm on the PC speaker to get the user's attention,
  1335.               but only if the System Variables $ALARMS and $SOUND are non-
  1336.               zero.  If $ALARMS *or* $SOUND are set to zero, the ALARM is
  1337.  
  1338.  
  1339.  
  1340.  
  1341.      Intellicomm v2.01               SCRIPT.DOC                             15
  1342.      
  1343.      
  1344.  
  1345.               ignored.  Icom automatically sets $ALARMS to 0 before running
  1346.               automated jobs.  You can change the value of $ALARMS and/or
  1347.               $SOUND by ASSIGNing 0 (off) or 1 (on) to them.
  1348.      BEEP     sounds a beep on the PC speaker to get the user's attention, but
  1349.               only if the System Variable $SOUND is non-zero.  If $SOUND is
  1350.               set to zero BEEP (all sound) is ignored.  Icom automatically
  1351.               sets $SOUND to 0 before running automated jobs.
  1352.      CHAT     enters into Chat Mode.  Control returns to the script when the
  1353.               user is finished chatting and presses [Esc] to exit Chat Mode.
  1354.      DEBUG    turns the script debugger on or off.
  1355.      EDIT     loads a text file for editing, positions to optional line #.
  1356.      FILEMAN  calls the Icom File Manager to display a given directory and/or
  1357.               filespec.  The user can Edit, View, Copy, Ren/Move, Delete, Find
  1358.               files, or display another directory.  Control returns to the
  1359.               script when the user exits the File Manager.
  1360.      HELP     displays a specific help topic (or the help index).
  1361.      HELPFIND similar to using the online help "Search" feature.  It searches
  1362.               all topics in the online help file for a given keyword, and
  1363.               displays all topics that contain the keyword to the user.
  1364.      LIST     displays a text file for viewing, positions to optional line #.
  1365.      LOADBIF  loads a new BIF into memory.
  1366.      LOADINI  loads a new main setup (.INI) file into memory.
  1367.      SAVEBIF  saves the current BIF information (in memory) to disk.
  1368.      SAVEINI  saves the current main setup data (in memory) to disk.
  1369.      TAGGER   enters the File Tagger, loading a specified catalog for viewing.
  1370.      TONE     sounds a specific tone on the speaker, for a specific duration.
  1371.      $ALARMS  determines whether alarms are heard or not (this is a main setup
  1372.               option and is used globally in Intellicomm).
  1373.      $OPSYSTYPE reports the Operating System in use on the computer (DESQview,
  1374.                 DOS, OS/2 or Windows).
  1375.      $SOUND   determines whether any sound at all is heard (beeps from the
  1376.               BBS, ALARMs, etc.  This is also a main setup option).
  1377.      GlobalStr[] is a global variable 'array' available to all scripts.  The
  1378.                  GlobalStr array stores parameters (if any) passed to a script
  1379.                  from DOS, Custom Commands, BIFs or other scripts, and is
  1380.                  otherwise useful for simply storing information semi-
  1381.                  permanently (for the duration of the Icom session) and for
  1382.                  other useful things.  See SCRTUTOR.DOC for more details on
  1383.                  GlobalStr.
  1384.  
  1385.      1.13  File Tagger Commands (Advanced use only)
  1386.  
  1387.      These commands allow you to manipulate File Tagger catalogs (databases)
  1388.      directly, and are for advanced script writers only.  Read INTRODUCTION TO
  1389.      DATABASE COMMANDS in SCRTUTOR.DOC before using these commands.
  1390.  
  1391.      CADDREC     adds a new record to the currently open (COPEN) catalog, and
  1392.                  updates the NDX's (indexes, used to sort catalogs) to include
  1393.                  the new record's data.
  1394.      CCLEARBUF   clears all $CXXXX_FLD variables and the record description
  1395.                  buffer.
  1396.      CCLEARDESC  clears only the record description buffer.
  1397.      CCLOSE      closes the currently open catalog.
  1398.      CDATE2DATE  converts a dBASE date (YYYYMMDD ... as dates are stored in
  1399.  
  1400.  
  1401.  
  1402.  
  1403.      Intellicomm v2.01               SCRIPT.DOC                             16
  1404.      
  1405.      
  1406.  
  1407.                  catalogs) to the date format defined by the user in the Icom
  1408.                  main setup.  [For displaying dates to the user.]
  1409.      CDATEDIFF   takes two dates in dBASE date format (YYYYMMDD) and stores
  1410.                  the difference (in days) between the two dates in a given
  1411.                  variable.
  1412.      CDELREC     delete or undelete a given record.  This command doesn't
  1413.                  actually remove the record from the database, it simply marks
  1414.                  a given record's status for the next CPACK (which actually
  1415.                  removes all deleted records).
  1416.      CEDITREC    displays the current record obtained with CGETREC for
  1417.                  editing.  This displays the same editing screen you see when
  1418.                  you select "Edit" to edit a record from within the Tagger. 
  1419.                  As well as being useful for record editing, this command can
  1420.                  be useful for debugging, since it shows you last record
  1421.                  obtained with CGETREC.  Once in edit mode the user can press
  1422.                  [PgUp], [PgDn], to browse through the catalog, just as in
  1423.                  edit mode.  Control is returned to your script when the user
  1424.                  presses [Esc] to exit edit mode.
  1425.      CEMPTY      executes a given command if the database opened with COPEN is
  1426.                  empty (e.g. CEMPTY RETURN, CEMPTY GOTO DONE, etc).
  1427.      CEXPORT     exports files in the currently open (COPEN) database to a
  1428.                  given text filename, in a given BIF format.  If the catalog
  1429.                  is currently sorted (CSETSORT), the $VIEW_DATE is observed
  1430.                  when exporting records (i.e. you can export only file newer
  1431.                  than a given date by setting $VIEW_DATE).
  1432.      CFLUSH      writes any data in the CPUTREC, CPUTDESC buffers to disk.
  1433.      CFORMATDESC re-formats the current file comment/description to a new line
  1434.                  length.  CGETREC automatically formats file comments to a
  1435.                  line length of 45 characters.  Use this command to make
  1436.                  comment lines longer or shorter.
  1437.      CGETDESC    gets a given line from the file comment/description field. 
  1438.                  Use CGETREC to get a record from the database before
  1439.                  CGETDESC.
  1440.      CGETREC     gets the next (or first, if no prior calls to CGETREC) record
  1441.                  from the currently open catalog, and stores the record data
  1442.                  in the System Variables listed below.
  1443.      CIMPORTNEW  imports *.NEW files lists (captured via your script, or by an
  1444.                  automated job) into the proper File Tagger catalog(s).  The
  1445.                  base filename of the .NEW list must be the same base filename
  1446.                  of the .BIF where the list was obtained.
  1447.      CIMPORTTEXT imports a given text file (BBS file listing) into the
  1448.                  currently open catalog, using a given BIF file list format.
  1449.      CNOTEREC    toggles the 'Noted' status of the current record and updates
  1450.                  the NDX's (indexes) with the new data.  Similar to hilighting
  1451.                  a record from within the Tagger and selecting "Note" from the
  1452.                  bottom menu.
  1453.      COPEN       opens an existing File Tagger catalog, or creates a new one
  1454.                  if the catalog doesn't exist.  Only the filename (no
  1455.                  extension or directory) is needed.
  1456.      CPACK       packs a given database (or the currently open database if one
  1457.                  is open and no catalog name is given), removing all records
  1458.                  flagged as "Deleted".  Also packs the .DBT (file comments
  1459.                  that are no longer attached to a valid record) and rebuilds
  1460.                  the .NDX files associated with the catalog.
  1461.  
  1462.  
  1463.  
  1464.  
  1465.      Intellicomm v2.01               SCRIPT.DOC                             17
  1466.      
  1467.      
  1468.  
  1469.      CPURGE      purges the catalog, deleting records older than the number of
  1470.                  days set by the user in the Icom main setup/Tagger settings. 
  1471.                  "Deleted" records are simply flagged as deleted.  They are
  1472.                  not removed from the catalog.  You must CPACK to physically
  1473.                  remove purged records.
  1474.      CPUTDESC    updates a given file comment line with new data.  CGETREC
  1475.                  gets the entire comment (all lines are stored in a memory
  1476.                  buffer) and formats it to 45 characters per line. 
  1477.                  CFORMATDESC re-format the comment to any number of characters
  1478.                  per line.  CGETDESC gets individual lines from the comment...
  1479.                  and CPUTDESC is used to replace ONE description line with new
  1480.                  data.
  1481.      CPUTREC     updates an existing record with new data.  CGETREC stores
  1482.                  record data in the System Variables listed below.  If you
  1483.                  modify any of the data (in memory) you must CPUTREC to write
  1484.                  the changes to disk.
  1485.      CSAVEBMARK  saves a new 'bookmark' in the currently open catalog, or
  1486.                  clears the existing bookmark.  The bookmark is where the
  1487.                  Tagger hilight bar automatically seeks to when the catalog is
  1488.                  displayed.
  1489.      CSAVESORT   saves the current sort order and direction (set with
  1490.                  CSETSORT) in the currently open catalog header.  The saved
  1491.                  sort order/direction will be in effect the next time the
  1492.                  catalog is COPENed or viewed in the Tagger.
  1493.      CSAVEVDATE  saves a new 'view date'.  The View Date is observed by the
  1494.                  File Tagger in browse or edit mode, and only files that were
  1495.                  imported on or after the current View Date are displayed. 
  1496.                  Similarly, CGETREC only gets records imported on or after the
  1497.                  View Date, if the catalog is sorted (CSETSORT).  Setting a
  1498.                  $VIEW_DATE temporarily is done by simply ASSIGNing the
  1499.                  $VIEW_DATE variable a new date.  To actually store a new View
  1500.                  Date in the catalog (so the Tagger will observe it the next
  1501.                  time the catalog is opened), you must CSAVEDATE to update the
  1502.                  catalog on-disk.  Tagged records are unaffected by the View
  1503.                  Date, and 'Noted' records are also unaffected by the View
  1504.                  Date if the user has that option turned on the the Icom main
  1505.                  setup/Tagger settings.
  1506.      CSEEK       allows you to seek to a specific record in the catalog (if no
  1507.                  sort order is set with CSETSORT), or to a 'relative' position
  1508.                  according to the sort order and $VIEW_DATE (top, bottom, 10
  1509.                  records back from current position, 100 records ahead from
  1510.                  current position, etc).
  1511.      CSETSORT    set the current sort order to 1 (sorted by Tag Status/
  1512.                  Location), 2 (Catalog Date/Filesize), 3 (Filename/File Date)
  1513.                  or -1 (unsorted).  Also set the direction of the sort
  1514.                  (forwards or backwards).  The current sort order is observed
  1515.                  by CGETREC, and CSEEK.
  1516.      CTAGALL     Tag, Note or Untag all records in the currently open catalog. 
  1517.                  The $VIEW_DATE is ignored; ALL records are game.
  1518.      CTAGREC     toggles the tag status of a given record (or the current
  1519.                  record obtained with CGETREC if no record # specified). 
  1520.                  Updates the indexes (sorting information) with the new data.
  1521.      CTELL       report the current record number (last obtained with
  1522.                  CGETREC).
  1523.  
  1524.  
  1525.  
  1526.  
  1527.      Intellicomm v2.01               SCRIPT.DOC                             18
  1528.      
  1529.      
  1530.  
  1531.      DATE2CDATE  Converts a date (see $DATE) in the format the user has set up
  1532.                  in the Icom main setup, to a dBASE-style date (YYYYMMDD).
  1533.      UPDATEDNDX  updates DOWNLOAD.NDX with any new files that were DOWNLOADed. 
  1534.                  Files listed in DOWNLOAD.NDX are never added to BBS file
  1535.                  listings (provided that the 'Use DOWNLOAD.NDX' item is turned
  1536.                  on in the main setup).  To update the directories scanned for
  1537.                  downloads, see the main setup/Tagger section "DOWNLOAD.NDX
  1538.                  Directories" option.
  1539.      $CAT_DIR    the Catalog Directory as defined in the main setup (where
  1540.                  Tagger catalogs are stored and created).
  1541.      $CAT_NAME   the filename of the currently open catalog (no extension). 
  1542.                  E.g. NEWFILES, FILELIST, etc.
  1543.      $CSORT_DIR  current sort direction (0 = forward, 1 = reversed)
  1544.      $CSORT_ORDER current sort order (-1 = Unsorted, 1 = Tag Status/Location,
  1545.                   2 = Catalog Date/Filesize, 3 = Filename/File Date).
  1546.      $CTOTAL     the total number of records in the catalog, ignoring the View
  1547.                  Date.
  1548.      $CVTOTAL    the total number of records in the catalog currently visible
  1549.                  according to the current View Date ($VIEW_DATE).  This
  1550.                  variable is set when you open a catalog, and is re-calculated
  1551.                  if you change the $VIEW_DATE variable.
  1552.      $VIEW_DATE  the current catalog $VIEW_DATE in the format YYYYMMDD.  COPEN
  1553.                  automatically sets this variable to the View Date stored in
  1554.                  the catalog (as defined by the user; or as defined by
  1555.                  Intellicomm's last import if Auto View Date Update is turned
  1556.                  on in the main setup).  If the catalog is set to use an index
  1557.                  with CSETSORT then CGETREC and CSEEK observe the date in
  1558.                  $VIEW_DATE, and only operate on records that were imported
  1559.                  ($CCDATE_FLD) on or after the View Date.  Records imported
  1560.                  prior to the View Date are ignored.
  1561.  
  1562.      The following variables are set by CGETREC when it obtains a record:
  1563.  
  1564.      $CREC_STAT  the status of the record ("A" = Active, "D" = Deleted).
  1565.      $CTAG_FLD   is set to "T" if the file is tagged, "N" if the file is
  1566.                  Noted, or blank if neither.
  1567.      $CPRIORITY_FLD the 'transfer priority' (a number from 1-200) of the
  1568.                  currently loaded catalog record.
  1569.      $CNAME_FLD  the File Name field in the format FILENAME.EXT.
  1570.      $CFDATE_FLD the File Date field in the format YYYYMMDD.
  1571.      $CSIZE_FLD  the File Size field.
  1572.      $CCDATE_FLD the Catalog Date field in the format YYYYMMDD (the date that
  1573.                  a record was imported to the catalog).  This is what
  1574.                  $VIEW_DATE compares to, in order to filter out older records.
  1575.      $CLOC_FLD   the BIF/Location field (base name of the .BIF needed to
  1576.                  download the files.  LOADBIF $CLOC_FLD loads the proper BIF
  1577.                  if necessary).
  1578.      $CAREA_FLD  the BBS Area (conference) the file is in (NEWAREA $CAREA_FLD
  1579.                  accesses the proper area if necessary).
  1580.      $CDAY_FLD   the Transfer Day set for this file (0 = Anyday, 1 = Sunday, 2
  1581.                  = Monday, etc).  Use $DOW to get the current day of the week
  1582.                  for comparison.
  1583.      $CFLAG_FLD  a general purpose flag field that EACH catalog record has,
  1584.                  that you can put to any use you see fit in scripts.
  1585.  
  1586.  
  1587.  
  1588.  
  1589.      Intellicomm v2.01               SCRIPT.DOC                             19
  1590.      
  1591.      
  1592.  
  1593.  
  1594.  
  1595.  
  1596.      Intellicomm v2.01               SCRIPT.DOC                             20
  1597.      
  1598.      
  1599.  
  1600.                       2.  USING THE DETAILED COMMAND SUMMARIES
  1601.  
  1602.  
  1603.      !!PLEASE READ THIS INTRODUCTION!!
  1604.  
  1605.      This section lists all the script commands in alphabetical order, giving
  1606.      detailed information about each command.  If you haven't looked at the
  1607.      section on SCRIPT VARIABLES yet, you should read at least the first
  1608.      couple of paragraphs so you'll know what variables are.  Variables are
  1609.      used in many of the examples below, and are referred to frequently in the
  1610.      command descriptions.  
  1611.  
  1612.      The Command Summaries require some explanation before you use them.  For
  1613.      each script command you will find the COMMAND itself, a SUMMARY showing
  1614.      any parameters the command takes, a DESCRIPTION outlining what the
  1615.      command's purpose is, the ERRORLEVELs the command will set (if any), a
  1616.      SEE ALSO section which points out similar script commands (if any), and
  1617.      an EXAMPLE showing how the command can be used in a real script.
  1618.  
  1619.      2.1  COMMAND Description
  1620.  
  1621.      The COMMAND itself is listed first, followed by a line of underscores.
  1622.  
  1623.      2.2  SUMMARY Description
  1624.  
  1625.      Following the command is the SUMMARY, which quickly shows whether any
  1626.      parameters are accepted, what parameter format is expected (string, 
  1627.      number, or command), and whether the parameter is mandatory or optional. 
  1628.      You'll never use a script command exactly as it's outlined in the SUMMARY
  1629.      section.  For example, the BOXGETS command (displays a box and gets a
  1630.      string from the keyboard) has the following summary:
  1631.  
  1632.      SUMMARY
  1633.  
  1634.       BOXGETS vDATA nMAXLENGTH [sTITLE] [sHELPLINE]
  1635.  
  1636.      You wouldn't actually put this in a script, specifying vDATA, etc., every
  1637.      time you used BOXGETS.  These are simply conventions used in all the
  1638.      SUMMARY sections, which quickly show you:
  1639.  
  1640.       1. Whether any parameters are accepted.  Above you can see that BOXGETS
  1641.          takes at least 'some' sort of parameters, even though you might not
  1642.          understand exactly 'what' as yet.
  1643.       2. It shows you which, if any, parameter(s) are optional.  Optional
  1644.          parameters are enclosed in square brackets and if you omit the
  1645.          parameter some default value is assumed.  The only way to tell
  1646.          exactly what default value will be used is to read the DESCRIPTION of
  1647.          the command (just below the SUMMARY section).
  1648.       3. It shows you what TYPE of parameters are expected, and, in general,
  1649.          what purpose the parameter serves.  The first letter of the parameter
  1650.          (always lowercase) shows you the type of parameter expected, while
  1651.          any characters that follow (always UPPERCASE) simply provide a short
  1652.          description of the purpose the parameter serves.  The BOXGETS command
  1653.          expects a 'v'ariable as the first parameter, a 'n'umber as the second
  1654.  
  1655.  
  1656.  
  1657.  
  1658.      Intellicomm v2.01               SCRIPT.DOC                             21
  1659.      
  1660.      
  1661.  
  1662.          parameter, and 's'trings (text and/or numbers) for the rest of the
  1663.          parameters.  Following is a list of the various parameter types used
  1664.          in the SUMMARY sections below:
  1665.  
  1666.          cPARAMETER  If a parameter begins with a lowercase 'c', then the
  1667.                      script command expects another script COMMAND as the
  1668.                      parameter.  This parameter type is used only by decision-
  1669.                      making commands, such as ONLINE, OFFLINE, WHEN, etc.
  1670.          nPARAMETER  If a parameter begins with a lowercase 'n', then the
  1671.                      script command expects a NUMBER (either a constant number
  1672.                      or a variable holding a number) as the parameter.
  1673.          sPARAMETER  If a parameter begins with a lowercase 's', then the
  1674.                      script command expects a STRING (either a constant string
  1675.                      in double quotes, or a variable holding a string) as the
  1676.                      parameter.  When a string parameter is expected, you can
  1677.                      also get away with specifying a numeric parameter (PRINT
  1678.                      1 is the same as PRINT "1").
  1679.          vPARAMETER  If a parameter begins with a lowercase 'v', then the
  1680.                      script command expects a VARIABLE as the parameter.  This
  1681.                      will only be true of one parameter per command, and it's
  1682.                      always the first parameter following the command.  It's
  1683.                      used by commands that assign new data (ADD, GETS, etc) to
  1684.                      script variables.
  1685.         [PARAMETER] If a parameter is in square brackets, then it is OPTIONAL.
  1686.  
  1687.         ...         If three periods follow all parameters, then the script
  1688.                     command accepts a variable number of parameters which can
  1689.                     be either strings or numbers.  This is normally used with
  1690.                     commands that display data to the screen (or write it to a
  1691.                     text file) to allow you to print the contents of one or
  1692.                     more variables among some constant text.  For example:
  1693.  
  1694.                             VARIABLE s "is"
  1695.                             VARIABLE n 1
  1696.                             PRINT "This " s " text line " n 
  1697.  
  1698.                     The above would print 'This is text line 1' (no quotes). 
  1699.                     It's just a convenience, and it allows you to avoid doing
  1700.                     this:
  1701.  
  1702.                             PRINTNC "This "      ;PRINTNC doesn't add a CR
  1703.                             PRINTNC s
  1704.                             PRINTNC " text line "
  1705.                             PRINT n
  1706.  
  1707.                     Any time you see three periods following all parameters in
  1708.                     the SUMMARY sections below, it means that the command will
  1709.                     group together all parameters you specify (up to the
  1710.                     maximum script line length of 256 characters).
  1711.  
  1712.      2.2.1  How to Specify Parameters
  1713.  
  1714.      Constant strings (in quotes) and constant numbers are NEVER mandatory. 
  1715.      You can always substitute ANY script parameter with ANY type of script
  1716.  
  1717.  
  1718.  
  1719.  
  1720.      Intellicomm v2.01               SCRIPT.DOC                             22
  1721.      
  1722.      
  1723.  
  1724.      variable:
  1725.  
  1726.       PRINT my_variable             ;user defined variable (VARIABLE command)
  1727.       PRINT $DATE                   ;System Variable
  1728.       PRINT GlobalStr[5]            ;Global array member (see SCRTUTOR.DOC)
  1729.       PRINT GlobalStr[my_variable]  ;Global member indexed by my_variable
  1730.       PRINT *minit                  ;Main Setup Variable (see Appendix)
  1731.       PRINT *[G]desc                ;BIF Variable (see Appendix)
  1732.  
  1733.      When a script command is expecting a numeric parameter (a number), if you
  1734.      omit the number (or you specify a variable that is holding a non-numeric
  1735.      value) 0 is assumed unless a specific default value is mentioned in the
  1736.      command DESCRIPTION section.  For example if you did this:
  1737.  
  1738.        variable x "here is some text"  ;store text in 'x'
  1739.        variable y
  1740.        add y x 10  ;y = x + 10
  1741.  
  1742.      then the result in 'y' would be 10, since 'x' is not holding a number (0
  1743.      + 10 = 10).  If you truly did want to "add" text to a number or vice
  1744.      versa (make a string longer), you'd use STRCAT:  Not ADD.
  1745.  
  1746.      NOTE: Script commands that accept another script command (such as the
  1747.      OFFLINE command demonstrated earlier) provide your scripts with decision-
  1748.      making abilities.  All commands that take a command parameter will ONLY
  1749.      execute the command IF a certain condition is true or false.  For
  1750.      example:
  1751.  
  1752.      ONLINE cCOMMAND
  1753.  
  1754.      The ONLINE command ONLY executes cCOMMAND (which signifies any other
  1755.      script command) IF the modem is currently offline.  The WHEN commmand
  1756.      ONLY executes cCOMMAND if/when specific text is found from the BBS, and
  1757.      so forth.  If the condition is false cCOMMAND is not executed, and Icom
  1758.      skips the rest of the script line, and proceeds to the next line of the
  1759.      script.
  1760.  
  1761.      2.3  ERRORLEVEL Description
  1762.  
  1763.      Listed in each ERRORLEVEL section are the numbers (if any) you can check
  1764.      by accessing the $ERRORLEVEL System Variable, after a script command
  1765.      finishes.  If no ERRORLEVEL section exists then the command doesn't
  1766.      modify the $ERRORLEVEL variable.
  1767.  
  1768.      For example, the GETS command gets keyboard input from the user, but you
  1769.      might want to check to see whether the user pressed the [Esc] key, or
  1770.      simply entered nothing.  You can test for these conditions by referring
  1771.      to the Detailed Command Summary of the GETS command, and looking at the
  1772.      ERRORLEVEL section:
  1773.  
  1774.       0  No errors, the user entered something.
  1775.       1  The user pressed the [Enter] key, but didn't enter anything.
  1776.       2  The user pressed the [Esc] key or right mouse button.
  1777.  
  1778.  
  1779.  
  1780.  
  1781.      Intellicomm v2.01               SCRIPT.DOC                             23
  1782.      
  1783.      
  1784.  
  1785.      In a script you could test for these conditions by doing something like
  1786.      the following:
  1787.  
  1788.       variable myvariable
  1789.  
  1790.       while 1               ;loop until BREAK
  1791.        gets myvariable 10   ;10 is the max characters the user can enter
  1792.  
  1793.        if $ERRORLEVEL = 0   ;[Esc] not hit, variable not empty
  1794.         print "Thanks for entering: " myvariable
  1795.         break               ;exit the WHILE loop
  1796.        else                 ;variable empty or [Esc] was pressed
  1797.         print "Please enter something, or press [Esc] to cancel."
  1798.        endif
  1799.       endwhile
  1800.  
  1801.      The $ERRORLEVEL variable remains valid only for a short time, until
  1802.      another script command modifies it.  Make sure you check for errors
  1803.      immediately after the command in question, before using any other
  1804.      commands, or the value of $ERRORLEVEL may not be valid.  If you must
  1805.      check $ERRORLEVEL at some later point, just assign it to your own
  1806.      variable immediately after the command, then check your own variable
  1807.      later:
  1808.  
  1809.       variable MyVariable
  1810.       variable MyErrorlevel
  1811.  
  1812.      GetAgain:
  1813.  
  1814.       gets MyVariable 10
  1815.       assign MyErrorlevel $ERRORLEVEL  ;save the value for later use
  1816.  
  1817.        ;you could not use other script commands which modified
  1818.        ; $ERRORLEVEL ... and later in the script:
  1819.  
  1820.       if MyErrorlevel <> 0             ;not equal to zero?
  1821.        msgwind "Please enter something!"
  1822.        goto GetAgain
  1823.       endif
  1824.  
  1825.  
  1826.  
  1827.  
  1828.      Intellicomm v2.01               SCRIPT.DOC                             24
  1829.      
  1830.      
  1831.  
  1832.                             3.  DETAILED COMMAND SUMMARY
  1833.  
  1834.  
  1835.      ADD______________________________________________________________________
  1836.  
  1837.      SUMMARY
  1838.  
  1839.       ADD vSUM nADDEND1 nADDEND2
  1840.  
  1841.      DESCRIPTION
  1842.  
  1843.       Adds nADDEND1 to nADDEND2 and stores the result in vSUM.  If either of
  1844.       the addends is missing (or contain text instead of a number), ADD will
  1845.       assume 0.
  1846.  
  1847.      SEE ALSO
  1848.  
  1849.       ADD, DIV, MUL, SUB
  1850.  
  1851.      EXAMPLE
  1852.  
  1853.       variable result
  1854.       ADD result 5 10   ;stores 5 + 10 (15) in variable 'result'
  1855.       print result
  1856.  
  1857.      ADDSLASH_________________________________________________________________
  1858.  
  1859.      SUMMARY
  1860.  
  1861.       ADDSLASH vSTRING
  1862.  
  1863.      DESCRIPTION
  1864.  
  1865.       To be used when building filenames, ADDSLASH checks vSTRING to ensure
  1866.       that it has a trailing back slash (\).  If not, one is added.  Note that
  1867.       if the very last character in vSTRING is a colon (a lone drive letter,
  1868.       such as C:), a slash is not added.
  1869.  
  1870.      SEE ALSO
  1871.  
  1872.       STRIPSLASH
  1873.  
  1874.      EXAMPLE
  1875.  
  1876.       variable customdir "C:\TEMP\"  ;default value
  1877.  
  1878.       printnc "Enter directory: "
  1879.       gets customdir 64
  1880.  
  1881.       ADDSLASH customdir   ;add trailing slash if user forgot to add one
  1882.  
  1883.      ALARM____________________________________________________________________
  1884.  
  1885.      SUMMARY
  1886.  
  1887.  
  1888.  
  1889.  
  1890.      Intellicomm v2.01               SCRIPT.DOC                             25
  1891.      
  1892.      
  1893.  
  1894.       ALARM nTIMES
  1895.  
  1896.      DESCRIPTION
  1897.  
  1898.       Sounds an alarm on the PC speaker nTIMES times.  The alarm sounded is
  1899.       the same alarm you hear in manual mode after a connection and a file
  1900.       transfer.  The alarm is only sounded if the user has BOTH of these main
  1901.       setup items turned on (both are on the "General" setup screen):
  1902.  
  1903.       | Sound . . . . . . . . . . On                                  |
  1904.       | Pager . . . . . . . . . . On                                  |
  1905.  
  1906.       You can force these items on by modifying the $SOUND and/or $ALARMS
  1907.       System Variables, if necessary.  If you do modify the values make sure
  1908.       you save the ORIGINAL values first, and restore them when you're done. 
  1909.       See the example below.
  1910.  
  1911.      SEE ALSO
  1912.  
  1913.       TONE, $ALARMS, $SOUND
  1914.  
  1915.      EXAMPLE 1
  1916.  
  1917.       ALARM 1                     ;sound the alarm once
  1918.  
  1919.      EXAMPLE 2
  1920.  
  1921.       variable old_alarms $alarms ;save original value of $ALARMS
  1922.       variable old_sound  $sound  ;save original value of $SOUND
  1923.  
  1924.       assign $alarms 1            ;1 = On, 0 = Off
  1925.       assign $sound  1            ;1 = On, 0 = Off
  1926.       ALARM 3                     ;this will DEFINITELY be sounded
  1927.       assign $alarms old_alarms   ;restore the original values
  1928.       assign $sound old_sound
  1929.  
  1930.      AND______________________________________________________________________
  1931.  
  1932.      SUMMARY
  1933.  
  1934.       AND vRESULT nNUM nBITMASK
  1935.  
  1936.      DESCRIPTION
  1937.  
  1938.       Performs a bitwise AND on nNUM using nBITMASK, and stores the result in
  1939.       vRESULT.  Unless you're a programmer, you probably will never use AND.
  1940.  
  1941.      SEE ALSO
  1942.  
  1943.       OR, SHL, SHR, XOR
  1944.  
  1945.      EXAMPLE
  1946.  
  1947.       variable someflag
  1948.  
  1949.  
  1950.  
  1951.  
  1952.      Intellicomm v2.01               SCRIPT.DOC                             26
  1953.      
  1954.      
  1955.  
  1956.       variable result
  1957.       AND result someflag 1
  1958.       if result = 0
  1959.        print "Bit 1 is CLEAR in variable 'someflag'"
  1960.       else
  1961.        print "Bit 1 is SET in variable 'someflag'"
  1962.       endif
  1963.  
  1964.      APPEND___________________________________________________________________
  1965.  
  1966.      SUMMARY
  1967.  
  1968.       APPEND sSOURCEFILE sTARGETFILE
  1969.  
  1970.      DESCRIPTION
  1971.  
  1972.       Adds the entire contents of file sSOURCEFILE to the end of file
  1973.       sTARGETFILE.  If sTARGETFILE exists, Control-Z characters (if any) are
  1974.       stripped from the end of the file before appending sSOURCEFILE.  If
  1975.       sTARGETFILE doesn't exist it is created if possible.
  1976.  
  1977.       You may (and should) specify a drive and path in both filenames.  If
  1978.       drives/directories are not specified, APPEND assumes the current DOS
  1979.       directory, which could be any drive/directory on the system unless your
  1980.       script issued a CHDIR command recently.
  1981.  
  1982.       NOTE: Neither the source nor the target file should be open (CAPTURE or
  1983.       FOPEN) when APPEND is called.  If you want to APPEND to (or from) the
  1984.       currently open CAPTURE file, close it first:
  1985.  
  1986.        CAPPUSH    ;save filename, open/closed/paused status
  1987.        CAPCLOSE   ;close it
  1988.        APPEND "D:\TEMP\MYDATA.TXT" $CAPTURE_FNAME
  1989.         ... or ...
  1990.        APPEND $CAPTURE_FNAME "D:\TEMP\TMPCAP.CAP"
  1991.        CAPPOP     ;restore to previous state
  1992.  
  1993.       If you have previously FOPENed either the sSOURCEFILE or sTARGETFILE,
  1994.       you should also FCLOSE the file before using APPEND on the file(s).  But
  1995.       FCLOSE causes the current file pointer position to be lost.  If you
  1996.       don't want to lose the position of the file pointer:
  1997.  
  1998.        VARIABLE fpos
  1999.        FTELL fpos myfile       ;store file pointer position
  2000.        ;where 'myfile' is the file handle of the open file
  2001.        FCLOSE myfile           ;close it
  2002.        APPEND ...              ;do your append to or from the file
  2003.        FOPEN myfile ...        ;repeat the FOPEN as it was done earlier
  2004.        FSEEK myfile fpos 1     ;seek back to same position
  2005.  
  2006.      ERRORLEVEL
  2007.  
  2008.       0  Successful.
  2009.       1  Source file couldn't be opened.
  2010.  
  2011.  
  2012.  
  2013.  
  2014.      Intellicomm v2.01               SCRIPT.DOC                             27
  2015.      
  2016.      
  2017.  
  2018.       2  Target file couldn't be opened.
  2019.  
  2020.      SEE ALSO
  2021.  
  2022.       APPENDS, APPENDSNC, COPY, FOPEN, FPUTS, FPUTSNC, FPUTC, FCLOSE
  2023.  
  2024.      EXAMPLE
  2025.  
  2026.       APPEND "C:\TEMP\MYFILE.TXT" "D:\ANOTHER.TXT"
  2027.  
  2028.      APPENDS__________________________________________________________________
  2029.      APPENDSNC________________________________________________________________
  2030.  
  2031.      SUMMARY
  2032.  
  2033.       APPENDS sTARGETFILE sSTRING
  2034.       APPENDSNC sTARGETFILE sSTRING
  2035.  
  2036.      DESCRIPTION
  2037.  
  2038.       APPENDS(tring), adds sSTRING to the file sTARGETFILE (a FILENAME.EXT
  2039.       preferably including a drive and/or directory; D:\PATH\FILENAME.EXT,
  2040.       etc).  If sTARGETFILE exists, Control-Z characters are stripped from the
  2041.       end of the file before sSTRING is added.  If the file doesn't exist, it
  2042.       is created if possible.
  2043.  
  2044.       sSTRING is followed by a Carriage Return (CR) and Line Feed (LF) to
  2045.       terminate the line in the file when APPENDS is used.  APPENDSNC (NC for
  2046.       'N'o 'C'arriage Return) does the same as APPENDS but doesn't terminate
  2047.       the line with CR/LF.  I.e. if you execute multiple APPENDSNC commands,
  2048.       you'll end up with a single line of text in sTARGETFILE.
  2049.  
  2050.       These commands can be used in your scripts to easily keep track of
  2051.       errors/status messages on-disk.  The LIST command can then be used to
  2052.       display the errors/messages when your script ends.  Or you can use FOPEN
  2053.       and FGETS to get each error/status line out of the file, and you can
  2054.       then test the results to do some "post script" error handling or
  2055.       cleanup.  You can also use APPENDS to add new "keywords" to the Tagger's
  2056.       keyword lists (stored in \ICOM\*.KWD files), and you can add notes to
  2057.       BIFs, etc.  
  2058.  
  2059.       NOTE 1: When specifying sTARGETFILE, if you omit the drive and path
  2060.       (D:\PATH\), the CURRENT DOS DIRECTORY is assumed which could be any
  2061.       drive and/or directory on the system.  Always specify full pathnames (or
  2062.       use a CHDIR command) to ensure that you're dealing with the proper
  2063.       directory.
  2064.  
  2065.       NOTE 2: The FOPEN command is not required prior to using APPENDS/
  2066.       APPENDSNC, and in fact the file you're appending to should NOT be open
  2067.       (Icom never leaves BIF, Keyword files, etc., open; it loads them into
  2068.       memory when necessary, then closes them).  APPENDS/NC automatically
  2069.       calls FOPEN prior to appending, and FCLOSE to close the file after the
  2070.       append.  Thus, if you're appending many lines to a text file it would be
  2071.       more efficient to use FOPEN (in append mode), FPUTS or FPUTSNC (several
  2072.  
  2073.  
  2074.  
  2075.  
  2076.      Intellicomm v2.01               SCRIPT.DOC                             28
  2077.      
  2078.      
  2079.  
  2080.       times, if necessary) to add your text, then FCLOSE.  This avoids the
  2081.       calls to FOPEN and FCLOSE which APPENDS/APPENDSNC automatically does for
  2082.       each line, and thus allows 'buffering' of the data for more efficient
  2083.       disk writes.
  2084.  
  2085.      ERRORLEVEL (Both commands)
  2086.  
  2087.       0  Successful.
  2088.       1  sTARGETFILE couldn't be opened.  Either you specified a bad
  2089.          "FILENAME.EXT" (or D:\PATH\FILENAME.EXT ... this command will NOT
  2090.          create directories), or the disk drive door was open, or there were
  2091.          no available DOS 'file handles'; the user can remedy the latter by
  2092.          increasing FILES= in the CONFIG.SYS file.
  2093.       2  sSTRING couldn't be appended (disk write error).  This usually occurs
  2094.          if the disk is full, but could be any number of disk write errors.
  2095.  
  2096.      SEE ALSO
  2097.  
  2098.       APPEND, FOPEN, FPUTSNC, FPUTS, FPUTC, FCLOSE
  2099.  
  2100.      EXAMPLE 1
  2101.  
  2102.       variable errorfile $HOME_DIR  ;put the Icom home dir in 'errorfile'
  2103.       strcat errorfile "ERRORS.!!!" ;add the filename
  2104.       delete errorfile              ;start fresh, kill last error file if any
  2105.        ;when errors are encountered in your script...
  2106.       APPENDS errorfile "<X has occurred> error."
  2107.        ;when your script ends:
  2108.       EXIST errorfile LIST errorfile  ;if errors occurred, list them 
  2109.  
  2110.      EXAMPLE 2
  2111.  
  2112.       variable filename $HOME_DIR "NOTE.KWD" ;Tagger 'Note File' keywords
  2113.  
  2114.        ;NOTE: You shouldn't  modify ANY Icom system files without notifying
  2115.        ; the user (in your script docs) and/or getting permission via keyboard
  2116.        ; input first.
  2117.  
  2118.       APPENDS filename " Note this text "  ;add a new keyword to 'Note'
  2119.  
  2120.       assign filename $BIF_DIR    ;put the Icom BIF Directory in 'filename'
  2121.       strcat filename $BIF_NAME   ;note: the .BIF extension isn't in here
  2122.       strcat filename ".BIF"      ; so we must add it
  2123.  
  2124.        ;BIF 'notes' are always at the end of a BIF and use the format:
  2125.        ; <TAB>"One line of note text"<CR><LF>
  2126.        ; ^I (Control-I) is a <TAB> character, and ^" is used to specify
  2127.        ; double quotes within strings (which must also be surrounded by
  2128.        ; double quotes)
  2129.  
  2130.       APPENDS filename "^I^"Add this line of text to the BIF notes.^""
  2131.  
  2132.      ASSIGN___________________________________________________________________
  2133.  
  2134.  
  2135.  
  2136.  
  2137.      Intellicomm v2.01               SCRIPT.DOC                             29
  2138.      
  2139.      
  2140.  
  2141.      SUMMARY
  2142.  
  2143.       ASSIGN vVARIABLE snNEWDATA
  2144.  
  2145.      DESCRIPTION
  2146.  
  2147.       Copies sNEWDATA (or nNEWDATA; text or a number) to vVARIABLE.  ASSIGN is
  2148.       used when you want to change the contents of an existing variable.  The
  2149.       variable vVARIABLE must be defined with the VARIABLE command (or must be
  2150.       a System/Main Setup/BIF Variable) before using ASSIGN.
  2151.  
  2152.       Note that as with all 's'tring-type parameters, you can also use numbers
  2153.       where necessary.  Either of these will assign the number 1 to
  2154.       'myvariable':
  2155.  
  2156.        ASSIGN myvariable "1"
  2157.        ASSIGN myvariable 1
  2158.  
  2159.      SEE ALSO
  2160.  
  2161.       VARIABLE
  2162.  
  2163.      EXAMPLES
  2164.  
  2165.        variable myvariable
  2166.  
  2167.        ASSIGN myvariable 0            ;myvariable = zero
  2168.        ASSIGN myvariable -1           ;myvariable = minus one
  2169.        ASSIGN myvariable "some text"  ;myvariable = "some text"
  2170.        ASSIGN myvariable $DOW         ;Store Day of Week in myvariable
  2171.        ASSIGN $DL_PROTOCOL "Z"        ;change download protocol to Zmodem
  2172.        ASSIGN $SCRN_COLOR 79          ;change current screen color to
  2173.                                       ; white on red (see COLOR CODES
  2174.                                       ; appendix)
  2175.  
  2176.      BEEP_____________________________________________________________________
  2177.  
  2178.      SUMMARY
  2179.  
  2180.       BEEP
  2181.  
  2182.      DESCRIPTION
  2183.  
  2184.       Sounds a beep on the PC speaker.
  2185.  
  2186.      SEE ALSO
  2187.  
  2188.       TONE
  2189.  
  2190.      EXAMPLE
  2191.  
  2192.       printnc "Roadrunner... "
  2193.       BEEP
  2194.       BEEP
  2195.  
  2196.  
  2197.  
  2198.  
  2199.      Intellicomm v2.01               SCRIPT.DOC                             30
  2200.      
  2201.      
  2202.  
  2203.       print "The coyote's after you."
  2204.       printnc "Roadrunner... "
  2205.       BEEP
  2206.       BEEP
  2207.       print "If he catches you you're through."
  2208.  
  2209.      BOX______________________________________________________________________
  2210.  
  2211.      SUMMARY
  2212.  
  2213.       BOX sBOXTITLE nX1 nY1 nX2 nY2
  2214.  
  2215.      DESCRIPTION
  2216.  
  2217.       The parameters, from left to right are:
  2218.  
  2219.         1. The Box Title (goes in the top border, as you see in Icom boxes).
  2220.         2. The x1 screen column (left to right) of the top corner.
  2221.         3. The y1 screen row (top to bottom) of the top corner.
  2222.         4. The x2 screen column of the bottom corner.
  2223.         5. The y2 screen row of the bottom corner.
  2224.  
  2225.       Screen coordinates start at 1, 1 (top left corner).  A standard text
  2226.       screen (mono or color) is 80 columns wide by 25 rows high (x coordinates
  2227.       range from 1-80, y coordinates range from 1-25).  EGA displays can
  2228.       display 42 rows (y coordinates range from 1-42), and VGA displays can
  2229.       display 50 rows (y coordinates range from 1-50).  The terminal status
  2230.       line is normally occupying the bottom-most screen line and CAN be
  2231.       overwritten with the BOX command (see the NOTE below).  You can check
  2232.       the current number of columns/rows on-screen by accessing the
  2233.       $SCRN_HEIGHT and $SCRN_WIDTH System Variables, if need be.
  2234.  
  2235.       NOTE: The information currently on-screen (if any) is overwritten by the
  2236.       BOX command.  If you wish to save the current screen before displaying
  2237.       your BOX and restore the screen after you're done with it, use VPUSH and
  2238.       VPOP before/after the BOX command, or use the WNDOPEN command which does
  2239.       the same thing as BOX but saves the current screen data, color and
  2240.       cursor coordinates.  Further, BOX does NOT set the logical screen window
  2241.       (see the WINDOW command) so PRINT, PRINTNC, CLS and GOTOXY do not
  2242.       observe the box limits.  Again, use WNDOPEN if this is what you want.
  2243.  
  2244.      SEE ALSO
  2245.  
  2246.       WNDOPEN, $SCRN_HEIGHT, $SCRN_WIDTH
  2247.  
  2248.      EXAMPLE
  2249.  
  2250.       vpush      ;save current screen
  2251.       BOX "Box Title" 1 1 $SCRN_WIDTH $SCRN_HEIGHT
  2252.        ;displays a box that covers the whole screen
  2253.       gotoxy 2 2
  2254.       pause "Press a key and this box is history..."
  2255.       vpop      ;restore screen saved with VPUSH
  2256.  
  2257.  
  2258.  
  2259.  
  2260.      Intellicomm v2.01               SCRIPT.DOC                             31
  2261.      
  2262.      
  2263.  
  2264.       BOX "Box Title" 20 10 60 16
  2265.        ;display a box with top corner at screen column 20, row 10
  2266.        ; and bottom corner at a screen column 60, row 16
  2267.        ; The coordinates are where the box border is drawn, so you'd have from
  2268.        ; 21, 11 to 59, 15 to write in, if you wanted to stay in the borders.
  2269.  
  2270.       printraw 23 13 $NORM_COLOR "Here is some text inside the box."
  2271.        ;printraw takes only two screen coordinates; row (x1) and column (y1)
  2272.        ; to start printing the message at.  $NORM_COLOR is the proper color
  2273.        ; to use inside boxes (it's the color BOX sets the inside of the
  2274.        ; all boxes to; as defined by the user in the main setup).
  2275.  
  2276.      BOXGETS__________________________________________________________________
  2277.  
  2278.      SUMMARY
  2279.  
  2280.       BOXGETS vINPUT nMAXLEN [sBOXTITLE] [sHELPLINE]
  2281.  
  2282.      DESCRIPTION
  2283.  
  2284.       Displays a centered box on the screen (adjusted to size according to the
  2285.       parameters specified after BOXGETS) gets user input of no more than
  2286.       nMAXLEN characters, and stores the user input in variable vINPUT. 
  2287.       sBOXTITLE (if any) is displayed in the box border and sHELPLINE (if any)
  2288.       is displayed centered inside the box just above the input field.  If
  2289.       variable vINPUT contains any data, it is offered to the user as a
  2290.       default response.
  2291.  
  2292.       If you wish to display a Help Line, but DON'T want a Box Title, simply
  2293.       specify "" as the Box Title (e.g. BOXGETS myvar 10 "" "Help Line").
  2294.  
  2295.       The box and user input line use the same colors that Icom uses on its
  2296.       own boxes/menus, etc., as defined by the user in the Icom main setup.
  2297.       Output from the BOXGETS command looks like this (with graphics
  2298.       characters instead of text) with a 'Help Line':
  2299.  
  2300.         +=| Box Title |====================================================+
  2301.         |                                                                  |
  2302.         |  This is the Help Line where you can give the user instructions  |
  2303.         |                                                                  |
  2304.         |  ><User input here>                                              |
  2305.         |                                                                  |
  2306.         +==================================================================+
  2307.  
  2308.       It looks like this if no Help Line is specified (size adjusted according
  2309.       to the 'len' parameter:
  2310.  
  2311.                               +=| Box Title |========+
  2312.                               |                      |
  2313.                               |  ><User input here>  |
  2314.                               |                      |
  2315.                               +======================+
  2316.  
  2317.       The contents of the screen that the box overwrites is saved prior to
  2318.  
  2319.  
  2320.  
  2321.  
  2322.      Intellicomm v2.01               SCRIPT.DOC                             32
  2323.      
  2324.      
  2325.  
  2326.       displaying the box and restored when the user presses [Enter] or the
  2327.       left mouse button, [Esc] or the right mouse button, or presses a key
  2328.       that matches a $HOTKEY_? variable (see the example).  When the box is on
  2329.       the screen, the user can type text (or numbers, symbols, etc.) on the
  2330.       input line to the maximum length specified by the 'len' parameter, and
  2331.       can use any of the following editing keys:
  2332.  
  2333.        [Left]       Moves the cursor one position to the left (if possible).
  2334.        [Right]      Moves the cursor one position to the right (if possible). 
  2335.  
  2336.        [Home]       Moves the cursor to the first character on the input line.
  2337.        [End]        Moves the cursor to the the position after the last
  2338.                     character on the input line.
  2339.        [Ctrl-Left]  Moves the cursor to the beginning of the previous word.
  2340.        [Ctrl-Right] Moves the cursor to the beginning of the next word.
  2341.        [Ctrl-End]   Deletes all characters from the cursor to the end of the
  2342.                     input line.
  2343.        [Ins]        Toggles insert/typeover mode (insert/typeover mode is
  2344.                     saved from one BOXGETS/GETS to the next).
  2345.        [Del]        Deletes the character under (at) the cursor pulling
  2346.                     characters from the right (if any) to the cursor position.
  2347.        [Backspace]  Deletes the character to the left of the cursor, moves the
  2348.                     cursor left one position, pulling characters to the right
  2349.                     (if any) along with it.
  2350.        [Enter]      Ends BOXGETS, restores the screen (see ERRORLEVEL below).
  2351.        [Esc]        Ends BOXGETS, restores the screen (see ERRORLEVEL below).
  2352.  
  2353.       The mouse can also be used to move the cursor by moving it left/right,
  2354.       and pressing the Left mouse button is equivalent to pressing the [Enter]
  2355.       key while pressing the Right mouse button is equivalent to pressing the
  2356.       [Esc] key.
  2357.  
  2358.       As well, while the user is entering text in the box, certain 'hotkeys'
  2359.       remain active for convenience.  The hotkeys available are:
  2360.  
  2361.        [Alt-A]  Call Editor (internal or external as defined in main setup).
  2362.        [Alt-J]  Jump to DOS shell.
  2363.        [Alt-N]  User-defined Hotkey 1 (defined in main setup).
  2364.        [Alt-O]  User-defined Hotkey 2    ""          "" 
  2365.        [Alt-V]  Call Archiver (as defined in main setup).
  2366.  
  2367.       If the user presses any of these hotkeys while entering text in the edit
  2368.       box, control is temporarily turned over to the task the user selected. 
  2369.       When the user exits the called task control returns to the edit box with
  2370.       everything exactly as it was before the hotkey was pressed.  The same
  2371.       applies to the GETS/GETSXY (BOXGETS without the box) commands.
  2372.       
  2373.       NOTE 1: Offering default responses (by placing the default in variable
  2374.       'var' before calling BOXGETS) is a handy feature, but won't be practical
  2375.       in all cases.  Where default responses are not possible, make sure that
  2376.       you CLEAR your variable before calling BOXGETS (ASSIGN myvariable ""
  2377.       clears a variable).  See the EXAMPLE for more information.
  2378.  
  2379.       NOTE 2: If a default is offered, the user can edit it using the cursor
  2380.  
  2381.  
  2382.  
  2383.  
  2384.      Intellicomm v2.01               SCRIPT.DOC                             33
  2385.      
  2386.      
  2387.  
  2388.       keys mentioned above.  However, if the user presses a NON-editing key (a
  2389.       letter, number, etc) as the first character, the default response is
  2390.       cleared automatically.  It's assumed that the user didn't want the
  2391.       default if anything but an editing key is pressed as the first key.
  2392.  
  2393.      ERRORLEVEL
  2394.  
  2395.       0   The user entered something (variable vINPUT contains data) then
  2396.           pressed the [Enter] key or left mouse button.
  2397.       1   The user pressed [Enter], but variable vINPUT is empty ... nothing
  2398.           was entered.
  2399.       2   The user pressed the [Esc] key or right mouse button to cancel.  If
  2400.           this occurs, the contents of variable vINPUT reverts to its original
  2401.           value whether the user changed it on the input line or not.
  2402.      256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns,
  2403.           the user pressed a key defined in one of the $HOTKEY_? variables. 
  2404.           See the example for details.
  2405.  
  2406.      SEE ALSO
  2407.  
  2408.       GETS, GETSXY, INKEY
  2409.  
  2410.      EXAMPLE 1
  2411.  
  2412.       variable myvariable 5  ;define 'myvariable', assign 5 as a default.
  2413.  
  2414.       BOXGETS myvariable 3 "Capturing Bulletin" "Enter bulletin to capture"
  2415.        ;a box would be displayed as outlined above, and on the 'User Input'
  2416.        ; line, 5 would be offered as a default bulletin number.
  2417.  
  2418.        ;if $ERRORLEVEL is equal to 0, the user entered something, so we
  2419.        ; execute the subroutine 'cap_bulletin'.
  2420.       if $ERRORLEVEL = 0 gosub cap_bulletin
  2421.  
  2422.       assign myvariable ""  ;clear the contents of 'myvariable' (no default).
  2423.       BOXGETS myvariable 64 "Box Title" "Help Line" ;example of no default
  2424.  
  2425.       return            ;exit the script
  2426.  
  2427.      cap_bulletin:
  2428.       send "B " myvariable " NS" ;send PCBoard [B]ulletin command
  2429.       waitfor "Command? " 120    ;wait 2 minutes to return to menu prompt.
  2430.       return                     ;return from subroutine
  2431.  
  2432.      EXAMPLE 2 ($HOTKEY_? USAGE -- ADVANCED)
  2433.  
  2434.       variable s
  2435.       
  2436.       assign s "SOMEFILE.EXT"  ;a default value for BOXGETS
  2437.       assign $HOTKEY_1 8448    ;Assign [Alt-F] to $HOTKEY_1 for BOXGETS
  2438.                                ; If the user presses [Alt-F] while entering
  2439.                                ; text, BOXGETS will set $ERRORLEVEL to 8448
  2440.                                ; (the value of the key pressed).
  2441.       BOXGETS s 64 "Upload" "Enter filename or press [Alt-F] for File Picker"
  2442.  
  2443.  
  2444.  
  2445.  
  2446.      Intellicomm v2.01               SCRIPT.DOC                             34
  2447.      
  2448.      
  2449.  
  2450.       assign $HOTKEY_1 0     ;clear the hotkey
  2451.  
  2452.       switch $ERRORLEVEL
  2453.        case 0                ;regular text was entered
  2454.         upload $UL_PROTOCOL s
  2455.        endcase
  2456.        case 1                 ;'s' is empty or [Esc] was pressed
  2457.        case 2
  2458.        endcase
  2459.        case 8448              ;[Alt-F] was pressed
  2460.         variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST
  2461.         stritem s $UL_PATH 1            ;store 1st dir on U/L PATH in s
  2462.         getfname s "Upload" "Please ^"Select^" one or more files to upload"
  2463.         notexist lstname goto skip_ul
  2464.         strins lstname "@" 0 1          ;@C:\ICOM\GETFNAME.LST
  2465.         upload "Z" lstname              ;uploads all files on the list
  2466.          ;Confused?  See the GETFNAME detailed summary
  2467.        endcase
  2468.       endswitch
  2469.  
  2470.         ;Note that the above can be accomplished with a simple UPLOAD command.
  2471.         ; If you don't specify a filename after UPLOAD, basically the same
  2472.         ; process as the above is carried out by UPLOAD.
  2473.  
  2474.      CADDREC__________________________________________________________________
  2475.  
  2476.      SUMMARY
  2477.  
  2478.       CADDREC
  2479.  
  2480.      DESCRIPTION
  2481.  
  2482.       CatalogADDRECord adds a new record to the currently open Tagger catalog
  2483.       (see COPEN).  The contents of the new record will be the current
  2484.       contents of the various Tagger record fields (explained in
  2485.       SCRTUTOR.DOC).  See the example for details.
  2486.  
  2487.       NOTE: The $CCDATE_FLD (Catalog Date field) is automatically set to
  2488.       'today' by CADDREC.
  2489.  
  2490.      ERRORLEVEL
  2491.  
  2492.       0 = Record successfully added.
  2493.       1 = Unable to add record (disk write error, etc).
  2494.  
  2495.      SEE ALSO
  2496.  
  2497.       CPUTREC
  2498.  
  2499.      EXAMPLE
  2500.  
  2501.       notexist "C:\TEST\SOMEFILE.ZIP" exit  ;some file you wish to import
  2502.  
  2503.        ;NOTEXIST (as well as EXIST,FINDFIRST,FINDNEXT) sets various System
  2504.  
  2505.  
  2506.  
  2507.  
  2508.      Intellicomm v2.01               SCRIPT.DOC                             35
  2509.      
  2510.      
  2511.  
  2512.        ; Variables which provide information about the file that was found.
  2513.        ; See FINDFIRST for details.  We're only interested in $FDATE here
  2514.        ; (the date of the file)
  2515.  
  2516.       copen "FILELIST"
  2517.       cclearbuf                             ;clear all the fields
  2518.  
  2519.       assign $CNAME_FLD "SOMEFILE.ZIP"
  2520.       date2cdate $CFDATE_FLD $FDATE         ;file date to dBASE format
  2521.       
  2522.        ;if you want to tag the file for upload you must either do it after
  2523.        ; the new record has been added (with CTAGREC) or you must be sure
  2524.        ; to include the "Upload Pending> BIFID1;BIFID2" line to the end of
  2525.        ; the file description, to tell Icom where to upload the file.  A
  2526.        ; simple tag isn't good enough when dealing with the FILELIST (upload) 
  2527.        ; catalog
  2528.        
  2529.       assign $CTAG_STAT "T"   ;tagged
  2530.       cputdesc "This is a description of SOMEFILE.ZIP.  It might continue on"
  2531.       cputdesc "for several lines...  See CPUTDESC for details."
  2532.       cputdesc "Upload Pending^P JOESBBS"
  2533.  
  2534.        ;Note that ^P (Ctrl-P) is the proper character to use after Upload
  2535.        ; Pending and Uploaded To.  This is the hard way to tag a file and
  2536.        ; it should only be attempted when adding new records with CADDREC
  2537.        ; (if even then).  Read on for an easier way.
  2538.  
  2539.        ;Once you get all the fields (in memory) set up the way you want them,
  2540.        ; go ahead and call CADDREC to add the new data to the catalog.
  2541.  
  2542.       CADDREC
  2543.  
  2544.       if $ERRORLEVEL = 0      ;was CADDREC successful?
  2545.        variable RecordNumber  ;Yes
  2546.        ctell RecordNumber     ;what record # did we add?
  2547.        print "Record #" RecordNumber " added to FILELIST catalog."
  2548.         ;you could perform 'CTAGREC RecordNumber "JOESBBS"' here and
  2549.         ; achieve the same effect as the (more difficult) tag above.
  2550.       else
  2551.        print "Unable to add record to FILELIST."
  2552.       endif
  2553.  
  2554.       cclose
  2555.  
  2556.      CAPCLOSE_________________________________________________________________
  2557.  
  2558.      SUMMARY
  2559.  
  2560.       CAPCLOSE
  2561.  
  2562.      DESCRIPTION
  2563.  
  2564.       Closes the current capture file, if open (no harm is done if the capture
  2565.       file was already closed).  To PAUSE the capture file without closing it,
  2566.  
  2567.  
  2568.  
  2569.  
  2570.      Intellicomm v2.01               SCRIPT.DOC                             36
  2571.      
  2572.      
  2573.  
  2574.       use the CAPPAUSE command.
  2575.  
  2576.      SEE ALSO
  2577.  
  2578.       CAPTURE, CAPPAUSE, $CAP_NAME, $CAP_STAT
  2579.  
  2580.      EXAMPLE
  2581.  
  2582.        dial "A BBS"   ;capture is normally opened automatically on connect
  2583.        CAPCLOSE       ;...use CAPCLOSE to close it if you like.
  2584.  
  2585.      CAPPAUSE_________________________________________________________________
  2586.  
  2587.      SUMMARY
  2588.  
  2589.       CAPPAUSE
  2590.  
  2591.      DESCRIPTION
  2592.  
  2593.       Toggles the pause status of the capture file (if open).  If the capture
  2594.       file is currently unpaused (capturing), then CAPPAUSE pauses it.  If
  2595.       paused, CAPPAUSE unpauses it.  While paused, nothing received from the
  2596.       BBS, or printed with PRINT, PRINTNC or PAUSE is written in the file.
  2597.  
  2598.       You can check the current state of the capture file by accessing the
  2599.       $CAP_STAT System Variable.
  2600.  
  2601.      SEE ALSO
  2602.  
  2603.       CAPPUSH, CAPPOP, CAPTURE, CAPCLOSE, $CAP_NAME, CAP_STAT
  2604.  
  2605.      EXAMPLE
  2606.  
  2607.       cappush
  2608.       if $CAP_STAT = 1 CAPPAUSE    ;pause if open
  2609.  
  2610.       print "This portion of the online session will not be captured."
  2611.       send "CHAT"
  2612.       chat
  2613.       
  2614.       cappop  ;restore the previous state (open/closed/paused)
  2615.  
  2616.      CAPSTAMP_________________________________________________________________
  2617.  
  2618.      SUMMARY
  2619.  
  2620.       CAPSTAMP
  2621.  
  2622.      DESCRIPTION
  2623.  
  2624.        Stamps the same type of header that Icom itself stamps:
  2625.  
  2626.      ==<< YY-MM-DD HH:MM:SS BIFID - BBS Name >>============================
  2627.  
  2628.  
  2629.  
  2630.  
  2631.      Intellicomm v2.01               SCRIPT.DOC                             37
  2632.      
  2633.      
  2634.  
  2635.       in the current capture file (if open) and if *capstamp (the main setup
  2636.       option 'Stamp Date/Time Cap Open' is on.
  2637.  
  2638.      ERRORLEVEL
  2639.  
  2640.      SEE ALSO
  2641.  
  2642.      EXAMPLE
  2643.  
  2644.       variable old_stamp *capstamp
  2645.  
  2646.       capture "NEWCAP.CAP"
  2647.       assign *capstamp 1       ;to make sure it gets stamped, whether the user
  2648.                                ; has this option turned on or not
  2649.       CAPSTAMP
  2650.  
  2651.       assign *capstamp old_stamp
  2652.  
  2653.      CAPPUSH__________________________________________________________________
  2654.      CAPPOP___________________________________________________________________
  2655.  
  2656.      SUMMARY
  2657.  
  2658.       CAPPUSH
  2659.       CAPPOP
  2660.  
  2661.      DESCRIPTION
  2662.  
  2663.       CAPPUSH saves the current $CAP_NAME (capture filename
  2664.       D:\PATH\FILENAME.EXT) and $CAP_STAT (open/closed/paused status) to an
  2665.       internal buffer.  CAPPOP restores the capture filename/status saved with
  2666.       the last CAPPUSH (multiple times, if necessary).  Every time you call
  2667.       CAPPUSH, you overwrite the previously saved values.  I.e. no "stack" is
  2668.       available to save multiple capture filenames.  You're free to implement
  2669.       your own form of CAPPUSH if you must save multiple capture filenames in
  2670.       your scripts:
  2671.  
  2672.        variable capname1 $CAPTURE_NAME
  2673.        variable capstat1 $CAPTURE_STAT
  2674.          ...later
  2675.        variable capname2 $CAPTURE_NAME
  2676.        variable capstat2 $CAPTURE_STAT
  2677.          ...restore as needed
  2678.        assign $CAPTURE_NAME capname2
  2679.        assign $CAPTURE_STAT capstat2
  2680.  
  2681.          ...etc.
  2682.  
  2683.      SEE ALSO
  2684.  
  2685.       CAPCLOSE, CAPPAUSE, CAPTURE, $CAP_NAME, $CAP_STAT
  2686.  
  2687.      EXAMPLE
  2688.  
  2689.  
  2690.  
  2691.  
  2692.      Intellicomm v2.01               SCRIPT.DOC                             38
  2693.      
  2694.      
  2695.  
  2696.       CAPPUSH                   ;save old capture filename/status
  2697.       capture "\TEMP\TEMP.CAP"  ;open a new capture file
  2698.       send "B 15 NS"            ;PCBoard, show bulletin #15 in non-stop mode
  2699.       waitfor "Command? "       ;wait for BBS main menu
  2700.       CAPPOP                    ;restore the original capture filename/state
  2701.  
  2702.      CAPTURE__________________________________________________________________
  2703.  
  2704.      SUMMARY
  2705.  
  2706.       CAPTURE [sCAPFILE ...]
  2707.  
  2708.      DESCRIPTION
  2709.  
  2710.       CAPTURE closes the current capture file (if open), then opens a new
  2711.       capture file.  sCAPFILE may contain the full D:\PATH\FILENAME.EXT
  2712.       (drive, path, filename, extension) of the new capture file.  If you omit
  2713.       D:\PATH\ or .EXT, the D:\PATH\ and/or .EXT is taken from the current
  2714.       contents of $CAP_NAME (the last capture file opened, or the default
  2715.       capture filename as defined in the Icom main setup).
  2716.  
  2717.       Note that CAPTURE accepts multiple parameters, and the purpose of this
  2718.       is to allow you to build filenames based on the contents of variables:
  2719.  
  2720.        variable mycapdrive "D:"
  2721.        variable mycapdir "\TEMP\CAP\"
  2722.        variable mycapfname "TEMP.CAP"
  2723.  
  2724.        CAPTURE mycapdrive mycapdir mycapfname
  2725.  
  2726.       The above is the same as CAPTURE "D:\TEMP\CAP\TEMP.CAP".
  2727.  
  2728.       If the sCAPFILE parameter is omitted (or is a blank) and the capture
  2729.       file is currently closed, CAPTURE prompts the user for a new capture
  2730.       filename.  If the capture file is currently open, the Close/Pause menu
  2731.       is displayed (same as pressing [Alt-L] from Terminal Mode).  Thus, you
  2732.       can use CAPTURE to interact with the user as well, possibly to prompt
  2733.       for a custom capture filename.
  2734.  
  2735.       When a capture is open, Icom appends each line sent from the BBS *and*
  2736.       any data your script displays with the PRINT, PRINTNC or PAUSE commands,
  2737.       to the end of the capture file.  CAPTURE always adds to the end of files
  2738.       if they exist; it never overwrites files.  If you wish to start a new
  2739.       capture file, simply use a DELETE, RENAME, or RENUMBER command prior to
  2740.       calling CAPTURE.
  2741.  
  2742.       You can later view the capture file to review the BBS session, using
  2743.       either an external text file viewer, or Icom's built-in File Viewer
  2744.       (also see the LIST command; you can also have your script display
  2745.       capture files via the File Viewer).  See the EXAMPLE below for useful
  2746.       capture techniques.
  2747.  
  2748.       NOTE 1: The "Stamp Date/Time Cap Open" item on the Icom main setup
  2749.       General Settings screen controls whether the CAPTURE command stamps
  2750.  
  2751.  
  2752.  
  2753.  
  2754.      Intellicomm v2.01               SCRIPT.DOC                             39
  2755.      
  2756.      
  2757.  
  2758.       newly opened capture files with a line similar to this:
  2759.  
  2760.       ==<< YY-MM-DD HH:MM:SS BIFNAME - BBS Description >>====================
  2761.  
  2762.       These lines can be useful in processing capture files after an online
  2763.       session (either by eye or with the script file I/O commands), since they
  2764.       give you both the date/time of the connection (always in the format YY-
  2765.       MM-DD HH:MM:SS [Year-Month-Day  Hour:Minute:Second]), and the BIF ID. 
  2766.       However, there may be times when you want to disable this capture
  2767.       stamping.  If the need arises you can do so by modifying the *capstamp
  2768.       Main Setup Variable:
  2769.  
  2770.         variable old_capstamp *capstamp  ;save old value
  2771.         assign *capstamp 0               ;0 = Off
  2772.         CAPTURE "SOMEFILE.CAP"           ;won't stamp date/time line on open
  2773.         assign *capstamp old_capstamp    ;restore previous value
  2774.  
  2775.       NOTE 2: As mentioned earlier, if you omit the drive, path, or extension
  2776.       when specifying the sCAPFILE parameter, CAPTURE simply "fills in" the
  2777.       portion you DO specify.  For example, if you did this:
  2778.  
  2779.         CAPTURE "C:\ICOM\LST\MYLIST.NEW"
  2780.         CAPTURE "ICOM"
  2781.  
  2782.       then the second CAPTURE command would capture to C:\ICOM\LST\ICOM.NEW. 
  2783.       Only a filename was specified in the second CAPTURE command, so that's
  2784.       all CAPTURE replaces.  This can be useful in many cases ... and can
  2785.       produce unexpected results in other cases if you don't keep it in mind. 
  2786.       To ensure that you're capturing to the exact drive/directory/filename/
  2787.       extension you want, make sure you SPECIFY them in the CAPTURE command.  
  2788.  
  2789.      ERRORLEVEL
  2790.  
  2791.       0  Successful capture open.
  2792.       1  Unable to open capture file (bad filename, disk full, or no file
  2793.          handles).  A status window (MSGWIND) will be displayed by CAPTURE
  2794.          automatically if the open fails, to notify the user.  So there's no
  2795.          need to display an error message in the script, but you might want to
  2796.          abort a specific task, such as sending a command to the BBS to
  2797.          display a long list of files, etc., if you get an error opening the
  2798.          file.
  2799.          Note also that if a disk write error occurs while Icom is updating
  2800.          (adding to) the capture file, an error is displayed to the user and
  2801.          the capture file is automatically closed.
  2802.  
  2803.      SEE ALSO
  2804.  
  2805.       CAPCLOSE, CAPPAUSE, DELETE, RENAME, RENUMBER, $CAP_NAME, $CAP_STAT
  2806.  
  2807.      EXAMPLE
  2808.  
  2809.       variable key
  2810.  
  2811.       CAPPUSH                    ;save current capture filename/status
  2812.  
  2813.  
  2814.  
  2815.  
  2816.      Intellicomm v2.01               SCRIPT.DOC                             40
  2817.      
  2818.      
  2819.  
  2820.       CAPTURE "\TEMP\BLT5.CAP"   ;close curent cap, open a new capture file
  2821.       send "B 5 NS"              ;PCBoard read bulletin 5, non-stop
  2822.       waitfor "Command?" 120
  2823.  
  2824.       msgopen "Capturing bulletin 1 to printer; ready printer and press a key"
  2825.       inkeyw key      ;pause for a keystroke or mouse click
  2826.       msgclose        ;close the message window
  2827.       send "B 1 NS"   ;Tell the BBS to display bulletin 1, non-stop
  2828.       CAPTURE $PRN    ;start capturing to the printer
  2829.       waitfor "Command?" 120
  2830.  
  2831.       CAPPOP          ;restore the original capture filename and state
  2832.  
  2833.      CCLEARBUF________________________________________________________________
  2834.  
  2835.      SUMMARY
  2836.  
  2837.       CCLEARBUF
  2838.  
  2839.      DESCRIPTION
  2840.  
  2841.       Clears $CCDATE_FLD, $CDAY_FLD, $CFDATE_FLD, $CFLAG_FLD, $CLOC_FLD,
  2842.       $CNAME_FLD, $CPRIORITY_FLD, $CSIZE_FLD, $CTAG_FLD, and the file (record)
  2843.       description buffer.  Use CCLEARBUF to clear the entire record buffer
  2844.       before you ASSIGN various items to various fields and CADDREC (add a new
  2845.       record to the catalog).  Note that CCLEARBUF doesn't clear any records
  2846.       on-disk.  It only clears the catalog record buffer (where records are
  2847.       loaded from disk when you perform a CGETREC).
  2848.  
  2849.      SEE ALSO
  2850.  
  2851.       CCLEARDESC
  2852.  
  2853.      EXAMPLE
  2854.  
  2855.       copen "NEWFILES"
  2856.  
  2857.       CCLEARDESC
  2858.       assign $NAME_FLD "SOMEFILE.EXT"
  2859.       assign $CLOC_FLD "BIFID"
  2860.       caddrec
  2861.       cclose
  2862.  
  2863.      CCLEARDESC_______________________________________________________________
  2864.  
  2865.      SUMMARY
  2866.  
  2867.       CCLEARDESC
  2868.  
  2869.      DESCRIPTION
  2870.  
  2871.       Clears the catalog description buffer (memory only).  The description
  2872.       buffer is located in memory and it is where file descriptions are loaded
  2873.       when you perform a CGETREC.  CGETDESC / CPUTDESC then allow you to
  2874.  
  2875.  
  2876.  
  2877.  
  2878.      Intellicomm v2.01               SCRIPT.DOC                             41
  2879.      
  2880.      
  2881.  
  2882.       access this memory buffer.
  2883.  
  2884.       Use CCLEARDESC to quickly clear out the description buffer, when you
  2885.       want to CPUTDESC an entirely new description in the buffer (such as
  2886.       clearing the description before using the FILE_ID.DIZ description).
  2887.  
  2888.      SEE ALSO
  2889.  
  2890.       CCLEARBUF
  2891.  
  2892.      EXAMPLE
  2893.  
  2894.       copen "NEWFILES"
  2895.       cgetrec
  2896.       CCLEARDESC
  2897.       cputdesc "This is a new description."
  2898.       cputrec
  2899.       cclose
  2900.  
  2901.      CCLOSE___________________________________________________________________
  2902.  
  2903.      SUMMARY
  2904.  
  2905.       CCLOSE
  2906.  
  2907.      DESCRIPTION
  2908.  
  2909.       Closes the currently open Tagger catalog (see COPEN).  CCLOSE is called
  2910.       automatically when your script ends, if you forget to call it yourself. 
  2911.       But you should get into the habit of doing it yourself in case it
  2912.       becomes necessary to remove this auto-CCLOSE protection in the future.
  2913.  
  2914.      SEE ALSO
  2915.  
  2916.       COPEN
  2917.  
  2918.      EXAMPLE
  2919.  
  2920.       ;See SCRTUTOR.DOC for real examples
  2921.  
  2922.       COPEN "NEWFILES"
  2923.       CCLOSE
  2924.  
  2925.      CDATE2DATE_______________________________________________________________
  2926.  
  2927.      SUMMARY
  2928.  
  2929.       CDATE2DATE vDATE sCDATE
  2930.  
  2931.      DESCRIPTION
  2932.  
  2933.       Converts a Catalog/dBASE date to the date format the user has set up in
  2934.       the Icom main setup.  Catalog dates are stored in the format YYYYMMDD
  2935.       (YearMonthDay), which is great for sorting an indexing... but not so
  2936.  
  2937.  
  2938.  
  2939.  
  2940.      Intellicomm v2.01               SCRIPT.DOC                             42
  2941.      
  2942.      
  2943.  
  2944.       great for human consumption.  Use CDATE2DATE to easily convert Catalog
  2945.       dates ($VIEW_DATE, $CCDATE_FLD, $CFDATE_FLD) to a more eye-pleasing
  2946.       format.
  2947.  
  2948.      ERRORLEVEL
  2949.  
  2950.       0  sCDATE contained a valid YYYYMMDD date, and it has been converted and
  2951.          stored in vDATE.
  2952.       1  sCDATE is not a valid date, and vDATE is empty.
  2953.  
  2954.      SEE ALSO
  2955.  
  2956.       DATE2CDATE
  2957.  
  2958.      EXAMPLE
  2959.  
  2960.       variable vdate
  2961.       variable fdate
  2962.       variable cdate
  2963.       copen "NEWFILES"
  2964.       CDATE2DATE vdate $VIEW_DATE   ;current View Date of catalog
  2965.  
  2966.       cgetrec                       ;grab a record (any one will do)
  2967.       CDATE2DATE fdate $CFDATE_FLD  ;File Date
  2968.       CDATE2DATE cdate $CCDATE_FLD  ;Catalog Date
  2969.  
  2970.       print "NEWFILES Catalog.  Current View Date: " vdate
  2971.       print "Filename    : " $CNAME_FLD
  2972.       print "File Size   : " $CSIZE_FLD
  2973.       print "File Date   : " fdate
  2974.       print "Catalog Date: " cdate
  2975.  
  2976.       cclose
  2977.  
  2978.      CDATEDIFF________________________________________________________________
  2979.  
  2980.      SUMMARY
  2981.  
  2982.       CDATEDIFF vDIFFERENCE sCDATE1 sCDATE2
  2983.  
  2984.      DESCRIPTION
  2985.  
  2986.       Subtracts sCDATE2 from sCDATE1 and stores the difference (in days) in
  2987.       vDIFFERENCE.  Both sCDATE1 and sCDATE2 must contain valid dates in
  2988.       Tagger catalog (dBASE) format: YYYYMMDD.
  2989.  
  2990.       NOTE: If sCDATE1 is more recent than sCDATE2, you'll get a negative
  2991.       number in vDIFFERENCE.  sCDATE2 is subtracted FROM sCDATE1, so sCDATE2
  2992.       should be the same as, or more recent than, sCDATE1.  You'll almost
  2993.       always use this to compare a record's Catalog Date ($CCDATE_FLD) or File
  2994.       Date ($CFDATE) with today's date ($DATE) ... and since you know that a
  2995.       Catalog Date can never be more recent than today's date, it's a simple
  2996.       matter to use today's date as the second date parameter.  A file date is
  2997.       another story, and many BBS operators do post files with dates well into
  2998.  
  2999.  
  3000.  
  3001.  
  3002.      Intellicomm v2.01               SCRIPT.DOC                             43
  3003.      
  3004.      
  3005.  
  3006.       the future (01-01-95, etc), to keep the file from being purged from the
  3007.       listings.  You can handle that problem as well.  See the example for
  3008.       details.
  3009.  
  3010.      SEE ALSO
  3011.  
  3012.       DATE2CDATE
  3013.  
  3014.      EXAMPLE
  3015.  
  3016.       variable diff
  3017.       variable today
  3018.  
  3019.        ;first, we must convert today's date to dBASE format before it'll be
  3020.        ; accepted by CDATEDIFF
  3021.  
  3022.       date2cdate today $DATE
  3023.  
  3024.       copen "NEWFILES"
  3025.       cgetrec           ;get a record
  3026.  
  3027.        ;While IF isn't smart enough to do a real date comparison, it works in
  3028.        ; this case since the dates are stored in the format YYYYMMDD.
  3029.        ; ASCII-wise, 0 is 'less than' 9, so if the current record has a year
  3030.        ; that is 'greater than' the current year, or a month 'greater than'
  3031.        ; the current month, or a day 'greater than' today ... we'll know that
  3032.        ; its date is more recent than today (in which case CDATEDIFF is
  3033.        ; invalid since we're comparing to 'today' in the example).  This ONLY
  3034.        ; works in this one case, with the dates stored in the format YYYYMMDD.
  3035.        ; See the IF summary for details on string comparisons (these dates are
  3036.        ; just strings of ASCII characters to IF).
  3037.  
  3038.       print "Filename: " $CNAME_FLD
  3039.  
  3040.       if $CFDATE_FLD > today    ;the File Date is greater than today's date?
  3041.        assign diff 0
  3042.       else
  3043.        cdatediff diff $CFDATE_FLD today
  3044.       endif
  3045.       print "File Age: " diff " day(s) old"
  3046.  
  3047.       cdatediff diff $CCDATE_FLD today
  3048.       print "Imported: " diff " day(s) ago"
  3049.  
  3050.       cclose
  3051.  
  3052.      CDELREC__________________________________________________________________
  3053.  
  3054.      SUMMARY
  3055.  
  3056.       CDELREC nRECNUMBER
  3057.  
  3058.      DESCRIPTION
  3059.  
  3060.  
  3061.  
  3062.  
  3063.      Intellicomm v2.01               SCRIPT.DOC                             44
  3064.      
  3065.      
  3066.  
  3067.       Toggles the deleted status of record nRECNUMBER in the currently open
  3068.       Tagger catalog (see COPEN).  With most other record-oriented commands
  3069.       the nRECNUMBER parameter is optional.  But it's mandatory with CDELREC
  3070.       so that you're always deleting precisely the record you had in mind.
  3071.  
  3072.  
  3073.      ERRORLEVEL
  3074.  
  3075.       0  Deleted status successfully toggled.
  3076.       1  Invalid nRECNUMBER or disk write error.
  3077.  
  3078.      EXAMPLE
  3079.  
  3080.       variable record
  3081.  
  3082.       copen "NEWFILES"
  3083.       csetsort -1      ;-1 = Unsorted (CGETREC ignores $VIEW_DATE)
  3084.  
  3085.        ;delete any records with a Catalog Date ($CCDATE_FLD) older than
  3086.        ; the View Date ($VIEW_DATE).
  3087.  
  3088.       while 1
  3089.        cgetrec
  3090.        if $errorlevel <> 0 break     ;end of catalog
  3091.  
  3092.        if $CREC_STAT = "D" continue  ;already deleted, skip it
  3093.  
  3094.          ;Note that using the IF command to compare dates is only valid when
  3095.          ; both dates are in the format YYYYMMDD, as is the case with
  3096.          ; $CCDATE_FLD and $VIEW_DATE.  You could not use $DATE and get
  3097.          ; a valid comparison, since $DATE does not use the format YYYYMMDD
  3098.          ; (though you can convert it to YYYYMMDD with a call to DATE2CDATE).
  3099.  
  3100.        if $CCDATE_FLD < $VIEW_DATE  ;older than View Date?
  3101.         ctell record                ;get the current record number for CDELREC
  3102.         CDELREC record  
  3103.        endif
  3104.       endwhile
  3105.  
  3106.       ;you'd have to call CPACK here to actually remove the deleted records
  3107.  
  3108.       cclose
  3109.  
  3110.      CEDITREC_________________________________________________________________
  3111.  
  3112.      SUMMARY
  3113.  
  3114.       CEDITREC [nRECNUMBER]
  3115.  
  3116.      DESCRIPTION
  3117.  
  3118.       Enters Tagger "Edit Mode", displaying either the current record (if
  3119.       nRECNUMBER is omitted) or record number nRECNUMBER.  The user can then
  3120.       edit the record, and press [PgUp] / [PgDn] to move to the next/previous
  3121.  
  3122.  
  3123.  
  3124.  
  3125.      Intellicomm v2.01               SCRIPT.DOC                             45
  3126.      
  3127.      
  3128.  
  3129.       records according to the current sort order (set with CSETSORT). 
  3130.       CEDITREC does not return until the user presses [Esc] to exit Edit Mode.
  3131.  
  3132.      EXAMPLE
  3133.  
  3134.  
  3135.      COPEN "NEWFILES"
  3136.      CSETSORT 1       ;Tag Status/Location, forward
  3137.      CEDITREC         ;Enter edit mode (top of catalog)
  3138.      CCLOSE
  3139.  
  3140.      CEMPTY___________________________________________________________________
  3141.  
  3142.      SUMMARY
  3143.  
  3144.       CEMPTY cCOMMAND
  3145.  
  3146.      DESCRIPTION
  3147.  
  3148.       Checks the currently open Tagger catalog (see COPEN) and executes
  3149.       cCOMMAND if it is empty (no valid file records except the header
  3150.       record).  If the catalog is NOT empty, cCOMMAND is skipped.
  3151.  
  3152.      EXAMPLE
  3153.  
  3154.       copen "NEWFILES"
  3155.       CEMPTY goto done
  3156.  
  3157.       while 1
  3158.        cgetrec
  3159.        if $errorlevel <> 0 break
  3160.        print $CNAME_FLD
  3161.       endwhile
  3162.  
  3163.      done:
  3164.       cclose
  3165.  
  3166.      CEXPORT__________________________________________________________________
  3167.  
  3168.      SUMMARY
  3169.  
  3170.       CEXPORT [sBIFNAME] [sTEXTFILE] [nEXPORTTYPE] [nNODISPLAY]
  3171.  
  3172.      DESCRIPTION
  3173.  
  3174.       Same as selecting "Tools|Export to Text File" from within the File
  3175.       Tagger.  CEXPORT exports all visible records (according to the View
  3176.       Date) in sBIFNAME format (according to the positions on the BIF
  3177.       "Bank/List" screen) to text file sTEXTFILE.  The records are written to
  3178.       sTEXTFILE in the current sort order (see CSETSORT).  If sTEXTFILE
  3179.       exists, it is appended to.  Otherwise, it is created.  If either
  3180.       sBIFNAME or sTEXTFILE is omitted, the user is prompted for the
  3181.       information, as in the File Tagger.
  3182.  
  3183.  
  3184.  
  3185.  
  3186.      Intellicomm v2.01               SCRIPT.DOC                             46
  3187.      
  3188.      
  3189.  
  3190.       nEXPORTTYPE is an optional number from 1 to 5, which controls the TYPE
  3191.       of files that are exported:
  3192.  
  3193.        1 = All files (Noted, Tagged and Untagged).
  3194.        2 = Tagged files only.
  3195.        3 = Noted files only.
  3196.        4 = Tagged or Noted files only.
  3197.        5 = Untagged files only.
  3198.  
  3199.       Again, if nEXPORTTYPE is omitted (or 0), the user is prompted for the
  3200.       type of files to export.
  3201.       
  3202.       nDISPLAY controls whether the export routines display any information to
  3203.       the screen.  If nNODISPLAY is 0 (zero) or is omitted, CEXPORTREC
  3204.       displays a message to the user while the export takes place.  If you
  3205.       want to hide this message, nNODISPLAY can be specified as a non-zero
  3206.       value.
  3207.  
  3208.      ERRORLEVEL
  3209.  
  3210.       0  Export successful.
  3211.       1  Catalog empty (nothing exported).
  3212.       2  sBIFNAME was omitted, CEXPORT prompted for a BIF format, and the user
  3213.          pressed [Esc].
  3214.       3  Unable to get the BIF "Bank/List" information from sBIFNAME (sBIFNAME
  3215.          doesn't exist, disk read error, BIF damaged, etc).
  3216.       4  sTEXTFILE was omitted, CEXPORT prompted for a text file to export to,
  3217.          and the user pressed [Esc].  OR nEXPORTTYPE was omitted, CEXPORT
  3218.          prompted for the type of files to export, and the user selected
  3219.          "Cancel" or pressed [Escl.
  3220.       5  Unable to open sTEXTFILE.  Most likely the filename was invalid
  3221.          (CEXPORT does not create directories), but could also be a disk write
  3222.          error or a lack of DOS file handles.  The user can remedy the latter
  3223.          by increasing FILES= in the CONFIG.SYS file.
  3224.       6  User abort ([Esc] key pressed before export complete).
  3225.       7  Disk read error.  Error reading catalog (disk read error, catalog
  3226.          damaged, etc).
  3227.       8  Disk write error.  Error writing to sTEXTFILE (disk full, various
  3228.          other disk errors).
  3229.  
  3230.      SEE ALSO
  3231.  
  3232.       CIMPORT
  3233.  
  3234.      EXAMPLE
  3235.  
  3236.       COPEN "NEWFILES"
  3237.  
  3238.       date2cdate $VIEW_DATE $DATE  ;View Date = today
  3239.       csetsort 3                   ;Sort by Filename/File Date
  3240.  
  3241.        ;export all records that were imported today (if any), sorted 
  3242.        ; by filename/file date
  3243.  
  3244.  
  3245.  
  3246.  
  3247.      Intellicomm v2.01               SCRIPT.DOC                             47
  3248.      
  3249.      
  3250.  
  3251.       CEXPORT PCB150 "C:\TEMP\ALLFILES.TXT" 1 ;1 = Export all files
  3252.  
  3253.        ;export any TAGGED records, sorted by Location (BBS the file is Tagged
  3254.        ; for).  The View Date is ignored on Tagged files so it's not necessary
  3255.        ; to reset the View Date.  Anything Tagged will be exported.
  3256.  
  3257.       csetsort 1                              ;Sort by Tag Status/Location
  3258.       CEXPORT PCB150 "C:\TEMP\TAGGED.TXT" 2   ;2 = Export Tagged files 
  3259.       cclose
  3260.  
  3261.      CFLUSH___________________________________________________________________
  3262.  
  3263.      SUMMARY
  3264.  
  3265.       CFLUSH
  3266.  
  3267.      DESCRIPTION
  3268.  
  3269.       Writes any data in the catalog buffers of the currently open catalog
  3270.       (see COPEN) to disk.  Disk input/output is 'buffered' when reading
  3271.       from/writing to Tagger catalogs (CADDREC, CGETREC, CPUTREC) meaning that
  3272.       memory buffers are used to group disk reads/writes together for more
  3273.       effecient transfers.  CFLUSH immediately writes any data in the write
  3274.       buffers to disk, and clears the contents of the buffers.  Note that
  3275.       CFLUSH is called automatically when you CCLOSE a catalog, and it
  3276.       normally will not be needed.
  3277.  
  3278.       If power outages are frequent in your area, or if you have just
  3279.       completed some critical script operations on a catalog and you want to
  3280.       ensure that the changes are written to disk immediately, you'll want to
  3281.       use CFLUSH.  Otherwise you should let the memory buffers do their work,
  3282.       and just CCLOSE the catalog (which performs a CFLUSH automatically) when
  3283.       you're finished with it.
  3284.  
  3285.      EXAMPLE
  3286.  
  3287.       copen "NEWFILES"
  3288.       ceditrec
  3289.       CFLUSH
  3290.  
  3291.      CFORMATDESC______________________________________________________________
  3292.  
  3293.      SUMMARY
  3294.  
  3295.       CFORMATDESC nWIDTH
  3296.  
  3297.      DESCRIPTION
  3298.  
  3299.       After calling CGETREC (get a Tagger catalog record), all file
  3300.       descriptions are formatted to a maximum length of 45 characters per line
  3301.       automatically.  CFORMATDESC re-formats a record's file description to a
  3302.       new line length of nWIDTH characters maximum.
  3303.  
  3304.      SEE ALSO
  3305.  
  3306.  
  3307.  
  3308.  
  3309.      Intellicomm v2.01               SCRIPT.DOC                             48
  3310.      
  3311.      
  3312.  
  3313.       CGETDESC, CPUTDESC
  3314.  
  3315.      EXAMPLE
  3316.       
  3317.       variable line
  3318.  
  3319.       copen "NEWFILES"
  3320.       while 1
  3321.        cgetrec
  3322.        if $ERRORLEVEL <> 0 break
  3323.        CFORMATDESC 65              ;65 characters per line
  3324.        cgetdesc line 1             ;get line 1 (will be 65 characters or less)
  3325.        print $CNAME_FLD "^I" line  ;^I is a TAB character
  3326.       endwhile
  3327.       cclose
  3328.  
  3329.      CGETC____________________________________________________________________
  3330.  
  3331.      SUMMARY
  3332.  
  3333.       CGETC vCHAR [nTIMEOUT]
  3334.  
  3335.      DESCRIPTION
  3336.  
  3337.       Gets a single character from the receive buffer and stores it in
  3338.       variable vCHAR.  If nTIMEOUT is specified and no characters are received
  3339.       by nTIMEOUT (specified in tenths of a second), CGETC ends and vCHAR will
  3340.       be empty.  If nTIMEOUT is omitted, CGETC waits for a character
  3341.       indefinitely.
  3342.  
  3343.       Note that CGETC doesn't deal directly with the COM port.  Only Icom's
  3344.       interrupt handler deals directly with the port, and the interrupt
  3345.       handler is driven (called) by hardware interrupts generated by the COM
  3346.       port itself.  If/when a character is received, the port sends an
  3347.       interrupt to the processor, and the processor (if it has time) turns
  3348.       control over to Icom's interrupt handler which then grabs the character
  3349.       and stores it in the receive buffer.
  3350.  
  3351.       CGETC simply checks Icom's "Receive Buffer" (size is configurable on the
  3352.       main setup/Terminal screen; it defaults to 4 Kbytes) to see if the
  3353.       interrupt handler stored any characters there.  What this means is that
  3354.       whether you call CGETC in your script or not, characters are still being
  3355.       taken from the COM port and stored in the Receive Buffer (until the
  3356.       buffer is about three quarters full, at which time the interrupt handler
  3357.       will activate Flow Control to pause the modems).  It works in the
  3358.       background, and is driven completely by the hardware itself ... and it's
  3359.       independant of both Intellicomm's terminal and scripts.  So if any
  3360.       characters are "lost", it's because your computer's processor (the
  3361.       hardware) couldn't turn control over to Icom's interrupt handler fast
  3362.       enough.  It has nothing to do with your lack of calling CGETC, or the
  3363.       speed at which CGETC is actually called.  And the only way to remedy the
  3364.       situation is either to get a faster processor, or to slow the COM port
  3365.       (baud rate) down.
  3366.  
  3367.  
  3368.  
  3369.  
  3370.      Intellicomm v2.01               SCRIPT.DOC                             49
  3371.      
  3372.      
  3373.  
  3374.       Further, there are certain commands you must avoid using, if you intend
  3375.       to use CGETC.  One TERMINAL command in your script can do the equivalent
  3376.       of many CGETC's and display the received character(s) on the screen
  3377.       (i.e. any characters in the Receive Buffer are "eaten" by TERMINAL
  3378.       commands, and your script, using CGETC, will never even know they were
  3379.       there). So unless you want Icom's terminal to steal characters before
  3380.       CGETC even sees them, don't call TERMINAL in and around your CGETC's. 
  3381.       This use of CGETC, for example, would get every other character received
  3382.       (at best):
  3383.  
  3384.        variable c
  3385.  
  3386.        while 1
  3387.         CGETC c 10
  3388.         printnc c
  3389.         terminal     ;TERMINAL does its own CGETC/printnc
  3390.        endwhile
  3391.  
  3392.       TERMINAL doesn't do just one CGETC, it does the equivalent of this:
  3393.  
  3394.        while $RXCNT > 0   ;$RXCNT is the number of chars in the Receive Buffer
  3395.         CGETC c
  3396.         printnc c
  3397.         inkey c           ;it also checks for and processes keystrokes
  3398.        endwhile
  3399.  
  3400.       I.e. *all* characters waiting in the receive buffer are handle by one
  3401.       single TERMINAL command.  Further, the following script commands call
  3402.       TERMINAL on their own:
  3403.  
  3404.        DELAY (use DELAYNC instead; it does not call TERMINAL)
  3405.        SEND (and its variations SENDNC/SENDNCP/SENDNP)
  3406.        SENDBIF
  3407.        WAITFOR
  3408.  
  3409.       So, you don't want to do this either (though you probably wouln't want
  3410.       to anyway):
  3411.  
  3412.        variable c
  3413.  
  3414.        while 1
  3415.         if $RXCNT > 0
  3416.          CGETC c
  3417.          sendnc c    ;SENDNC calls TERMINAL, so CGETC is useless
  3418.         endif   
  3419.        endwhile
  3420.  
  3421.      ERRORLEVEL
  3422.  
  3423.       0  Character received and stored in vCHAR.
  3424.       1  nTIMEOUT elapsed and no character was received.  Variable vCHAR will
  3425.          be empty in this case.
  3426.  
  3427.      SEE ALSO
  3428.  
  3429.  
  3430.  
  3431.  
  3432.      Intellicomm v2.01               SCRIPT.DOC                             50
  3433.      
  3434.      
  3435.  
  3436.       CGETS, RXBUF, TERMINAL
  3437.  
  3438.      EXAMPLE
  3439.  
  3440.       variable c
  3441.       CGETC c 100   ;wait 10 seconds maximum, then abort
  3442.       
  3443.       if $ERRORLEVEL > 0 print "Timeout."   ;one way to check...
  3444.       if c = "" print "Timeout."            ;another way to check
  3445.  
  3446.        ;If you don't use a timeout, you should make sure something is
  3447.        ; waiting in the receive buffer before you call CGETC
  3448.  
  3449.       if $RXCNT > 0 CGETC c
  3450.  
  3451.        ;variable 'c' will definitely have a character if $RXCNT is
  3452.        ; greater than (>) zero and there's no need to check $ERRORLEVEL.
  3453.  
  3454.      CGETDESC_________________________________________________________________
  3455.  
  3456.      SUMMARY
  3457.  
  3458.       CGETDESC vLINEBUF nLINENUM
  3459.  
  3460.      DESCRIPTION
  3461.  
  3462.       Gets description line number nLINENUM from the current Tagger catalog
  3463.       record (see below) and stores it in variable vLINEBUF.  Before using
  3464.       CGETDESC you must COPEN a Tagger catalog, and call CGETREC to get a
  3465.       record.  CGETDESC is only valid after a call to CGETREC.
  3466.  
  3467.       File description lines are formatted to a maximum of 45 characters per
  3468.       line by CGETREC.  Thus CGETDESC gets 45 characters of the description
  3469.       maximum, by default.  To change this line length, you can call
  3470.       CFORMATDESC after CGETREC.
  3471.  
  3472.      ERRORLEVEL
  3473.  
  3474.       0  Description line number nLINENUM was successfully loaded into
  3475.          vLINEBUF.
  3476.       1  There was no description line numbered nLINENUM (you've reached the
  3477.          end of the description, or it was empty to begin with).
  3478.  
  3479.      SEE ALSO
  3480.  
  3481.       CFORMATDESC, CGETREC 
  3482.  
  3483.      EXAMPLE
  3484.  
  3485.       This example demonstrates the entry of a file description to a BBS,
  3486.       during an upload.  Such a script could be plugged in to the "Description
  3487.       (@SCRIPTNAME)" item on the BIF "File" screen.  When this is the case,
  3488.       Intellicomm will already have the catalog open and will already have
  3489.       obtained the next tagged record (CGETREC), and will already have found
  3490.  
  3491.  
  3492.  
  3493.  
  3494.      Intellicomm v2.01               SCRIPT.DOC                             51
  3495.      
  3496.      
  3497.  
  3498.       the BBS "Enter Description" prompt.  Thus, all the script has to do is
  3499.       enter the description to the BBS.  Using the example below, you could
  3500.       make modifications (add a couple of WAITFORs or the like) to handle any
  3501.       curves a BBS developer can dream up.
  3502.  
  3503.       variable linenum 1
  3504.       variable linedat
  3505.  
  3506.       CGETDESC linedat 1                ;get line 1
  3507.       strblank linedat goto no_descrip  ;if blank, goto no_descrip
  3508.  
  3509.       while 1                           ;endless loop (until BREAK)
  3510.        CGETDESC linedat linenum 
  3511.        if $errorlevel = 1 break         ;no more description lines
  3512.        delay 10                         ;pause for a second (let BBS catch up)
  3513.        send linedat
  3514.        if linenum >= *[F]flmx break     ;Max Lines (BIF "File" screen)
  3515.        inc linenum                      ;INCrement (linenum = linenum + 1)
  3516.       endwhile
  3517.  
  3518.       if *[F]flmx > 1 send ""           ;If more than 1 line permitted, send
  3519.                                         ; [Enter] on a blank line
  3520.       return
  3521.  
  3522.      no_descrip:
  3523.       send "No description was available for this file."
  3524.       return
  3525.  
  3526.      CGETREC__________________________________________________________________
  3527.  
  3528.      SUMMARY
  3529.  
  3530.       CGETREC [nRECNUM]
  3531.  
  3532.      DESCRIPTION
  3533.  
  3534.       Loads either the current record (CTELL) or record number nRECNUM from
  3535.       the currently open catalog.  Please see INTRODUCTION TO DATABASE
  3536.       COMMANDS in file SCRTUTOR.DOC (included with Intellicomm) for detailed
  3537.       information.
  3538.  
  3539.      ERRORLEVEL
  3540.  
  3541.       0 = Record successfully loaded.
  3542.       1 = Unable to load record (end of catalog or nRECNUM is an invalid
  3543.           record number).
  3544.  
  3545.      SEE ALSO
  3546.  
  3547.       COPEN, CCLOSE
  3548.  
  3549.      EXAMPLE
  3550.  
  3551.       copen "NEWFILES"
  3552.  
  3553.  
  3554.  
  3555.  
  3556.      Intellicomm v2.01               SCRIPT.DOC                             52
  3557.      
  3558.      
  3559.  
  3560.       while 1
  3561.        CGETREC
  3562.        if $ERRORLEVEL > 0 break   ;end of catalog
  3563.       endwhile
  3564.  
  3565.      CGETS____________________________________________________________________
  3566.  
  3567.      SUMMARY
  3568.  
  3569.       CGETS vLINEBUF [nMAXCHARS] [sENDCHAR] [nTIMEOUT]
  3570.  
  3571.      DESCRIPTION
  3572.  
  3573.       Gets a line of input from the current COM port ($COM_PORT) and stores it
  3574.       in variable vLINEBUF.  Input is terminated when any of the following
  3575.       occurs:
  3576.  
  3577.       1. nMAXCHARS number of characters have been received.  150 characters
  3578.       (the maximum allowed) is assumed if nMAXCHARS is zero or is omitted.
  3579.  
  3580.       2. Either a Carriage Return or character sENDCHAR is received.  Note
  3581.       that neither a Carriage Return nor sENDCHAR is stored in vLINEBUF, if
  3582.       received.
  3583.  
  3584.       3. nTIMEOUT tenths of a second have elapsed (only if nTIMEOUT is
  3585.       specified).
  3586.  
  3587.       CGETS uses the equivalent of CGETC to get each character from the COM
  3588.       port.  Please see CGETC for more detailed information.
  3589.  
  3590.      ERRORLEVEL
  3591.  
  3592.       0  vLINEBUF contains one or more characters, and nTIMEOUT did not lapse.
  3593.       1  vLINEBUF is empty.  Either nTIMEOUT elapsed before a character was
  3594.          received, or nENDCHAR was the first character received.
  3595.       2  nTIMEOUT was specified, and the timeout period elapsed before a
  3596.          Carriage Return or nENDCHAR was received, or before nMAXCHARS were
  3597.          received.
  3598.  
  3599.      SEE ALSO
  3600.  
  3601.       CGETC
  3602.  
  3603.      EXAMPLE
  3604.  
  3605.      variable UserName
  3606.  
  3607.      sendnc "Please enter your name: "
  3608.      CGETS UserName 50 "^M" 60
  3609.  
  3610.      send "^M^JWelcome, " UserName "."
  3611.  
  3612.      CHAT_____________________________________________________________________
  3613.  
  3614.  
  3615.  
  3616.  
  3617.      Intellicomm v2.01               SCRIPT.DOC                             53
  3618.      
  3619.      
  3620.  
  3621.      SUMMARY
  3622.  
  3623.       CHAT
  3624.  
  3625.      DESCRIPTION
  3626.  
  3627.       Enters chat mode (same as pressing [Alt-T] from Terminal mode).  This
  3628.       command does not return until the users presses [Esc] to exit chat mode.
  3629.  
  3630.      EXAMPLE
  3631.  
  3632.       print "Entering chat mode..."
  3633.       CHAT
  3634.  
  3635.      CHECKVERSION_____________________________________________________________
  3636.  
  3637.      SUMMARY
  3638.  
  3639.       CHECKVERSION sMINIMUMVERSION
  3640.  
  3641.      DESCRIPTION
  3642.  
  3643.       CHECKVERSION is meant to be used as the first command in a script that
  3644.       is distributed to the general public.  It checks the current Intellicomm
  3645.       version number, and aborts the script with the following message if the
  3646.       version of Intellicomm executing the script is lower than
  3647.       sMINIMUMVERSION:
  3648.  
  3649.      Sorry, this script requires Intellicomm sMINIMUMVERSION or above.
  3650.  
  3651.       (where sMINIMUMVERSION is the version you specify).  sMINIMUMVERSION can
  3652.       specify the major version number only ("2") or the major version and the
  3653.       first decimal ("2.0") or the full version number ("2.00").  Only the
  3654.       portion you specify in sMINIMUMVERSION is checked.
  3655.  
  3656.       NOTE: CHECKVERSION will not be very useful until Intellicomm v1.00 is no
  3657.       longer in use, since Icom v1.00 did not support the CHECKVERSION command
  3658.       at thus if your v2.0x script is executed under Icom v1.00, Icom v1.00
  3659.       will simply ignore the command and continue to execute the script
  3660.       anyway.  Further, until new script commands/variables/concepts are
  3661.       introduced in the future, there's no need to check the version number. 
  3662.       So... keep CHECKVERSION in mind for the future, but don't bother with it
  3663.       for the time being.
  3664.  
  3665.      ERRORLEVEL
  3666.  
  3667.       None.  If sMINIMUMVERSION is higher than the current Intellicomm
  3668.       version, CHECKVERSION aborts the script.
  3669.  
  3670.      SEE ALSO
  3671.  
  3672.       $BETA_VERSION, $MAJOR_VERSION, $MINOR_VERSION
  3673.  
  3674.      EXAMPLE
  3675.  
  3676.  
  3677.  
  3678.  
  3679.      Intellicomm v2.01               SCRIPT.DOC                             54
  3680.      
  3681.      
  3682.  
  3683.       CHECKVERSION "2"    ;is the major version 2.xx or greater?  If not the
  3684.                           ; script aborts
  3685.  
  3686.       CHECKVERSION "2.0"  ;is v2.0x or greater?
  3687.  
  3688.  
  3689.       CHECKVERSION "2.01" ;is v2.01 or greater?
  3690.  
  3691.      CHDIR____________________________________________________________________
  3692.  
  3693.      SUMMARY
  3694.  
  3695.       CHDIR sNEWDIR
  3696.  
  3697.      DESCRIPTION
  3698.  
  3699.       Changes to a new drive and/or directory.  Similar to the DOS 'CHDIR'
  3700.       command, but this command actually changes the current drive as well
  3701.       (DOS's CHDIR simply changes the current directory of a drive but leaves
  3702.       you on the current drive).  You can specify a drive alone, a drive and
  3703.       directory, or a directory alone (to change directories on the current
  3704.       drive).  You can also specify subdirectories (CHDIR "\ICOM\LST").
  3705.  
  3706.      ERRORLEVEL
  3707.       
  3708.       0 = Successful.
  3709.       1 = Unsuccessful.
  3710.  
  3711.      SEE ALSO
  3712.  
  3713.       $CURDIR
  3714.  
  3715.      EXAMPLE
  3716.  
  3717.       variable old_dir $CUR_DIR        ;store current directory in 'old_dir'
  3718.  
  3719.       CHDIR "a:"                       ;change to drive A:
  3720.       if $ERRORLEVEL = 0               ;successful if 0
  3721.        dos ""                          ;DOS shell
  3722.        CHDIR old_dir                   ;change back to original
  3723.      drive/directory
  3724.       else
  3725.        print "Unable to change to A:"
  3726.       endif
  3727.  
  3728.      CIMPORTNEW_______________________________________________________________
  3729.  
  3730.      SUMMARY
  3731.  
  3732.       CIMPORTNEW
  3733.  
  3734.      DESCRIPTION
  3735.  
  3736.       Imports all new files lists (*.NEW) from the Intellicomm "List
  3737.  
  3738.  
  3739.  
  3740.  
  3741.      Intellicomm v2.01               SCRIPT.DOC                             55
  3742.      
  3743.      
  3744.  
  3745.       Directory" (\ICOM\LST).  This is the same as selecting "Tools | Import
  3746.       BBS Lists (*.NEW)" from the File Tagger.
  3747.  
  3748.       The lists are imported into either the Catalog Name defined on the BIF
  3749.       "Bank/List" screen, or the NEWFILES catalog if no custom catalog is
  3750.       defined.
  3751.  
  3752.       No catalogs need be opened (COPEN) before calling CIMPORTNEW.
  3753.  
  3754.       CIMPORTNEW is automatically executed after all automated jobs, but if
  3755.       you use stand-alone scripts exclusively to carry out your online
  3756.       sessions, you'll have to call it yourself.
  3757.  
  3758.      SEE ALSO
  3759.  
  3760.       CIMPORTTEXT
  3761.  
  3762.      EXAMPLE
  3763.  
  3764.      print "Importing *.NEW"
  3765.      CIMPORTNEW
  3766.  
  3767.      CIMPORTTEXT______________________________________________________________
  3768.  
  3769.      SUMMARY
  3770.  
  3771.       CIMPORTTEXT [sFILESPEC] [sBIFNAME]
  3772.  
  3773.      DESCRIPTION
  3774.  
  3775.       Imports the file(s) specified by sFILESPEC into the currently open
  3776.       catalog, using the filename/date/size (etc.) positions from the sBIFNAME
  3777.       (a BIF or BIF template) "Bank/List" screen.  This is the same as
  3778.       selecting "Tools | Import from Text File" from the File Tagger.
  3779.  
  3780.       If sFILESPEC and/or sBIFNAME is missing, the user is prompted for the
  3781.       information.  Wildcards (?, *) may be used in sFILESPEC to specify
  3782.       multiple files (\ICOM\CAP\*.CAP, etc).
  3783.  
  3784.       NOTE: The catalog you wish to import to must be opened first using the
  3785.       COPEN command.
  3786.  
  3787.      ERRORLEVEL
  3788.  
  3789.       0  Import successful.
  3790.       1  sFILESPEC was omitted, and the user pressed [Esc] when prompted for a
  3791.          filespec.
  3792.       2  sFILESPEC not found.
  3793.       3  sBIFNAME is an invalid BIF.
  3794.  
  3795.      SEE ALSO
  3796.  
  3797.       CIMPORTNEW
  3798.  
  3799.  
  3800.  
  3801.  
  3802.      Intellicomm v2.01               SCRIPT.DOC                             56
  3803.      
  3804.      
  3805.  
  3806.      EXAMPLE
  3807.  
  3808.      copen "NEWFILES"
  3809.      CIMPORTTEXT "C:\ICOM\CAP\ICOM.CAP" "PCB150"
  3810.      cclose
  3811.  
  3812.  
  3813.      CLS______________________________________________________________________
  3814.  
  3815.      SUMMARY
  3816.  
  3817.       CLS [nCOLOR]
  3818.  
  3819.      DESCRIPTION
  3820.  
  3821.       Clears the current screen WINDOW to nCOLOR if specified, or to the
  3822.       current screen color ($SCRN_COLOR) if nCOLOR is omitted.   Also moves
  3823.       the  cursor to the top left corner of the WINDOW (same as GOTOXY 1 1). 
  3824.       See the COLOR CODES appendix for color numbers to use in nCOLOR.
  3825.  
  3826.      SEE ALSO
  3827.  
  3828.       ERASELINE, SCROLL, $SCRN_COLOR, $TERM_COLOR
  3829.  
  3830.      EXAMPLE
  3831.  
  3832.       CLS $TERM_COLOR   ;default terminal color
  3833.       msgwind "You now have a clear screen"
  3834.  
  3835.      CNOTEREC_________________________________________________________________
  3836.  
  3837.      SUMMARY
  3838.  
  3839.       CNOTEREC [nRECNUM]
  3840.  
  3841.      DESCRIPTION
  3842.  
  3843.       TOGGLES the Noted status of the record specified by nRECNUM (or the
  3844.       current record if nRECNUM is 0 [zero] or omitted).  If nRECNUM is
  3845.       specified, that record number is noted/un-noted.  If nRECNUM is omitted,
  3846.       the current record (last record obtained via CGETREC) is noted/un-noted.
  3847.  
  3848.       Using CNOTEREC is similar to highlighting a given record in Tagger
  3849.       browse mode and selecting "Note".  I.e. if the record is Noted and you
  3850.       CNOTEREC it, it becomes un-noted.  If the record is un-noted and you
  3851.       CNOTEREC it, it becomes noted.
  3852.  
  3853.      ERRORLEVEL
  3854.  
  3855.       0  CNOTEREC was successful.
  3856.       1  Unable to load nRECNUM (if specified).
  3857.       2  The current record (or nRECNUM) is marked as "deleted".  Deleted
  3858.          records cannot be noted or un-noted.  This errorlevel is returned
  3859.          only to eliminate confusion: you should never "undelete" a deleted
  3860.  
  3861.  
  3862.  
  3863.  
  3864.      Intellicomm v2.01               SCRIPT.DOC                             57
  3865.      
  3866.      
  3867.  
  3868.          record to Note it.  If the record is deleted, either the user deleted
  3869.          it for a reason; or Icom has already successfully downloaded the
  3870.          file.
  3871.       3  Unable to switch the Note status (likely a disk write error).  If you
  3872.          get this error, try a CPACK to rebuild the indexes.
  3873.  
  3874.      SEE ALSO
  3875.  
  3876.       CTAGREC
  3877.  
  3878.      EXAMPLE 1
  3879.  
  3880.       copen "newfiles"
  3881.       cgetrec
  3882.       CNOTEREC
  3883.       cclose
  3884.  
  3885.      COPEN____________________________________________________________________
  3886.  
  3887.      SUMMARY
  3888.  
  3889.       COPEN sCATNAME
  3890.  
  3891.      DESCRIPTION
  3892.  
  3893.      Opens a File Tagger catalog for reading and/or writing (both).  sCATNAME
  3894.      is the base name of the catalog, with no drive/path or extension.  The
  3895.      catalog must exist in the Catalog Directory ($CAT_DIR).  If sCATNAME is
  3896.      not found in $CAT_DIR, it is created.
  3897.  
  3898.      Each catalog is comprised of five files:
  3899.  
  3900.       CATNAME.DBF  dBASE-compatible database holds filenames, etc.
  3901.       CATNAME.DBT  dBASE-compatible memo file holds EXTENDED file comments. 
  3902.                    The extended comment is any file description lines after
  3903.                    the primary (first) description line.
  3904.       CATNAMET.NDX dBASE-compatible index file holds the information necessary
  3905.                    to sort CATNAME.DBF by "Tag Status/Location" (as seen in
  3906.                    the File Tagger).
  3907.       CATNAMEC.NDX Same as above but holds information necessary to sort
  3908.                    CATNAME.DBF by "Catalog Date/Filesize" (as seen in the File
  3909.                    Tagger).
  3910.       CATNAMEN.NDX Another index that holds information necessary to sort
  3911.                    CATNAME.DBF by "Filename/File Date" (as seen in the File
  3912.                    Tagger).
  3913.  
  3914.      All five files are either opened or created when you call COPEN.
  3915.      No D:\PATH\ or .EXT is accepted in the sCATNAME parameter.  All File
  3916.      Tagger catalogs must reside in the Catalog Directory ($CAT_DIR).  You're
  3917.      free to keep catalogs in other directories if you like, but if you do you
  3918.      must make sure to COPY or RENAME (move from one directory to another)
  3919.      them before you call COPEN, or change the $DBF_PATH System Variable to
  3920.      point to a different directory (making sure you restore to the original
  3921.      value before your script exits).
  3922.  
  3923.  
  3924.  
  3925.  
  3926.      Intellicomm v2.01               SCRIPT.DOC                             58
  3927.      
  3928.      
  3929.  
  3930.      Further, you cannot open more than one catalog at a time with COPEN,
  3931.      unlike FOPEN which does allow up to 10 files to be open at once.  If a
  3932.      catalog is currently open when you call COPEN, it will be automatically
  3933.      closed before the new catalog is opened.  Note that when this happens,
  3934.      the contents of the $CXXXX_FLD variables and the file description is NOT
  3935.      cleared.  I.e. you can COPEN one catalog, get a record, then COPEN
  3936.      another catalog, CADDREC or CPUTREC (the same record) to copy record from
  3937.      one catalog to another.  Here's an example that copies all Tagged files
  3938.      from the NEWFILES catalog into another catalog called CUSTOM:
  3939.  
  3940.        variable last_rec 0
  3941.  
  3942.        while 1
  3943.         copen "NEWFILES"
  3944.         csetsort 1 0          ;set to Tag Status/Location sort; Noted files
  3945.                               ; come first, Tagged second, then Untagged
  3946.         if last_rec > 0       ;seek back to our original postion
  3947.          cgetrec last_rec     ; in NEWFILES if we have a 'last_rec'
  3948.         endif                 ; (see CTELL below)
  3949.         cgetrec               ;get the next record
  3950.         if $ERRORLEVEL <> 0 break     ;exit loop at end of catalog
  3951.         if $CTAG_FLD = "N" continue   ;skip noted records (Noted sort first)
  3952.         if $CTAG_FLD <> "T" break     ;exit loop once Tagged files are done
  3953.         ctell last_rec        ;save the current record number
  3954.         copen "CUSTOM"        ;close NEWFILES/open a cutom catalog
  3955.         caddrec               ;add the Tagged NEWFILES record to the catalog
  3956.        endwhile
  3957.  
  3958.      COPEN also automatically sets the $VIEW_DATE System Variable to the View
  3959.      Date stored in the catalog header (date of last import, or manual View
  3960.      Date set by the user).  It also sets the current sort order (CSETSORT) to
  3961.      the order set by the user the last time the catalog was viewed.  If you
  3962.      leave $VIEW_DATE alone, ONLY records that were imported on or after the
  3963.      $VIEW_DATE will be returned by CGETREC.  To view all records in the
  3964.      database, ASSIGN $VIEW_DATE "19900101" (Jan 1st, 1990... or any date
  3965.      that's older than Intellicomm).
  3966.  
  3967.      For more information on COPEN and File Tagger catalogs in general, please
  3968.      see the INTRODUCTION TO DATABASE COMMANDS section in the file
  3969.      SCRTUTOR.DOC (the script tutorial included with Intellicomm).
  3970.  
  3971.      ERRORLEVEL
  3972.  
  3973.       0  Catalog successfully opened (may have been created).
  3974.       1  Unable to open catalog.  Either the sCATNAME parameter in the COPEN
  3975.          command was an invalid filename (could not create), or the disk is
  3976.          full, or a disk write error occurred, or the existing catalog is
  3977.          damaged ... or DOS was out of file handles (increase FILES= in your
  3978.          CONFIG.SYS file).  COPEN will display a status window indicating the
  3979.          reason for the failure.
  3980.  
  3981.  
  3982.      SEE ALSO
  3983.  
  3984.  
  3985.  
  3986.  
  3987.      Intellicomm v2.01               SCRIPT.DOC                             59
  3988.      
  3989.      
  3990.  
  3991.       CCLOSE
  3992.  
  3993.      EXAMPLE
  3994.  
  3995.       COPEN "NEWFILES"  ;open the default 'download' catalog
  3996.       cclose
  3997.       COPEN "FILELIST"  ;open the 'upload' catalog
  3998.       cclose
  3999.        ;You can find much more meaningful examples in SCRTUTOR.DOC.
  4000.  
  4001.      COPY_____________________________________________________________________
  4002.  
  4003.      SUMMARY
  4004.  
  4005.       COPY sSOURCEFILE sTARGETFILE
  4006.  
  4007.      DESCRIPTION
  4008.  
  4009.       Copies sSOURCEFILE (the source filename) to sTARGETFILE (the destination
  4010.       filename), overwriting any file of the same destination filename.  Both
  4011.       sSOURCEFILE and sTARGETFILE can (and should) include the full
  4012.       D:\PATH\FILENAME.EXT of the files.  If the D: (drive) is omitted in
  4013.       either parameter, the current drive ($CURDRIVE) is assumed.  If the
  4014.       \PATH\ (or \PATH1\PATH2\, etc) is omitted in either paramater, the
  4015.       current directory ($CURDIR) is assumed.
  4016.  
  4017.       This command copies either binary or text files, and it maintains the
  4018.       original file date/time stamp (from the source file) on the newly
  4019.       created destination file.  This command does NOT create directories.  If
  4020.       the directory specified in the destination filename does not exist, the
  4021.       COPY command will fail ($ERRORLEVEL 3).
  4022.  
  4023.       Like the DOS 'COPY' command, if you do not specify drives/directories in
  4024.       the source or destination filenames, the current DOS drive/directory is
  4025.       assumed.  So make sure you specify directories unless you're sure of the
  4026.       current directory (use $CURDIR to get the current directory, or CHDIR to
  4027.       change directories first, if necessary).  UNLIKE the DOS 'COPY' command,
  4028.       you cannot use wildcards (*, ?) in the source or destination filenames. 
  4029.       If you wish to use wildcards, use COMMAND.COM's COPY using the script
  4030.       DOS command (e.g. DOS "copy *.* \temp").  The script equivalent is
  4031.       faster than shelling out to COMMAND.COM though, if you don't need
  4032.       wildcards.
  4033.  
  4034.      ERRORLEVEL
  4035.  
  4036.       0  Successful copy.
  4037.       1  Source and destination are the same filename.
  4038.       2  Unable to find/open the source file.
  4039.       3  Unable to create the destination file.
  4040.       4  Disk write error writing to destination (disk full usually, the
  4041.          portion of the destination that was written is deleted).
  4042.       5  Disk error reading source file, or disk error writing destination
  4043.          file (as above, the portion of the destination written is deleted).
  4044.       6  Filesize of destination (after copy) is not the same as the size of
  4045.  
  4046.  
  4047.  
  4048.  
  4049.      Intellicomm v2.01               SCRIPT.DOC                             60
  4050.      
  4051.      
  4052.  
  4053.          the source file (the destination file is deleted).
  4054.  
  4055.      SEE ALSO
  4056.  
  4057.       APPEND, APPENDS, APPENDSNC, DIRFIND, DISKFIND, DISKFREE, DOS, EXIST,
  4058.       FILESIZE, FNSTRIP, LOCATEFILE, MKDIR, NOTEXIST
  4059.  
  4060.      EXAMPLE
  4061.  
  4062.       variable source
  4063.       variable destination
  4064.  
  4065.       print "Enter source filename:"
  4066.       gets source 80                     ;get 80 characters max
  4067.       print "Enter destination drive, path and filename:"
  4068.       gets destination 80
  4069.       COPY source destination
  4070.       if $ERRORLEVEL = 0                 ;copy successful?
  4071.        print source " copied to " destination
  4072.       else
  4073.        print "Unable to copy file."
  4074.       endif
  4075.  
  4076.      CPACK____________________________________________________________________
  4077.  
  4078.      SUMMARY
  4079.  
  4080.       CPACK [sCATALOG_NAME]
  4081.  
  4082.      DESCRIPTION
  4083.  
  4084.       Physically removes any records marked as "deleted" from sCATALOG_NAME
  4085.       (or the currently open catalog, if sCATALOG_NAME is omitted).  Also
  4086.       removes any unattached extended file descriptions from the .DBT, and
  4087.       rebuilds the three indexes (.NDX) related to sCATALOG_NAME.
  4088.  
  4089.      ERRORLEVEL
  4090.  
  4091.      SEE ALSO
  4092.  
  4093.       CDELREC, CPURGE
  4094.  
  4095.      EXAMPLE 1
  4096.  
  4097.       copen "NEWFILES"
  4098.       cpurge           ;kill old records as configured in the Icom main setup
  4099.                        ; (optional)
  4100.       CPACK
  4101.       cclose
  4102.  
  4103.      EXAMPLE 2
  4104.  
  4105.       CPACK "NEWFILES"  ;COPEN/CCLOSE are done by CPACK.
  4106.  
  4107.  
  4108.  
  4109.  
  4110.      Intellicomm v2.01               SCRIPT.DOC                             61
  4111.      
  4112.      
  4113.  
  4114.      CPURGE___________________________________________________________________
  4115.  
  4116.      SUMMARY
  4117.  
  4118.       CPURGE [sCATNAME]
  4119.  
  4120.      DESCRIPTION
  4121.  
  4122.       Marks untagged/noted records in sCATNAME as deleted.  If sCATNAME is
  4123.       omitted, the currently open catalog is assumed.  CPURGE uses two Icom
  4124.       main setup variables to perform the purge:
  4125.  
  4126.        *prgnote  (Tagger Settings, item "Purge Noted # Days Old")
  4127.        *purge    (Tagger Settings, item "Purge Untagged # Days Old")
  4128.  
  4129.       If *prgnote is 0 (zero), no Noted records are deleted.  If *purge is 0
  4130.       (zero), no Untagged records are deleted.
  4131.  
  4132.      SEE ALSO
  4133.  
  4134.       CDELREC, CPACK
  4135.  
  4136.      EXAMPLE
  4137.  
  4138.       COPEN "NEWFILES"
  4139.       CPURGE
  4140.       CPACK
  4141.       CCLOSE
  4142.  
  4143.      CPUTDESC_________________________________________________________________
  4144.  
  4145.      SUMMARY
  4146.  
  4147.       CPUTDESC sNEWTEXT nLINE
  4148.  
  4149.      DESCRIPTION
  4150.  
  4151.       Appends a new description line (if nLINE is 0), or replaces an existing
  4152.       description line (if nLINE is 1 or greater) to the currently loaded file
  4153.       description.  Before using CPUTDESC a catalog must be opened with COPEN,
  4154.       and a record must be loaded using CGETREC.
  4155.  
  4156.       CPUTDESC does not modify the description on-disk in the catalog -- it
  4157.       works only with the description memory buffer, similar to the catalog
  4158.       $CXXXX_FLD variables.  To save a description you modify with CPUTDESC,
  4159.       you must save the catalog record back (from memory) to disk with
  4160.       CPUTREC.
  4161.  
  4162.       Technically what CPUTDESC does is to first locate description line
  4163.       number nLINE in the description memory buffer (or seek to the END of the
  4164.       description of nLINE is 0).  It then deletes the existing text (in the
  4165.       memory buffer ONLY) on that line, then inserts sNEWTEXT (if any).  If
  4166.       sNEWTEXT is blank ("") then line number nLINE is simply removed.
  4167.  
  4168.  
  4169.  
  4170.  
  4171.      Intellicomm v2.01               SCRIPT.DOC                             62
  4172.      
  4173.      
  4174.  
  4175.       Note that you may wish to use CFORMATDESC to re-format the description
  4176.       to a different line length before using CGETDESC or CPUTDESC. 
  4177.       Descriptions are formatted to a maximum of 45 characters per line by
  4178.       CGETREC.
  4179.  
  4180.      ERRORLEVEL
  4181.  
  4182.       0  Description line number nLINE was non-zero, and the line did exist. 
  4183.          The contents of that line was either replaced with sNEWTEXT, or the
  4184.          line was removed (if sNEWTEXT was blank).
  4185.       1  There was no description line number nLINE, and nothing was done. 
  4186.          sNEWTEXT was not added.  It would be a programming error to get this
  4187.          error code, since you shouldn't be replacing existing description
  4188.          lines until you know (a) how many lines already exist, and (b) what
  4189.          the contents of those lines was.  It would make no sense to do this:
  4190.  
  4191.           CGETREC
  4192.           CPUTDESC "Replace line 4 with this text." 4
  4193.  
  4194.           Since the only time you'd want to replace line 4 is if you KNEW that
  4195.           there was a line 4, and you knew what it contained.  If you 'did' do
  4196.           something like the above, and line 4 didn't exist in the
  4197.           description, you'd get $ERRORLEVEL 1 and "Replace line 4 with this
  4198.           text."  wouldn't be added.  It would make more sense to do this:
  4199.  
  4200.           cgetrec
  4201.           cgetdesc myvariable 4   ;get line 4 (CGETDESC also sets $ERRORLEVEL)
  4202.           if $ERRORLEVEL = 0      ;did line 4 exist? (yes if $ERRORLEVEL = 0)
  4203.            if myvariable = "Some text you want to replace."
  4204.              ;NOW you can go ahead specifying line 4, since you know it
  4205.              ; exists, and you know that the line contained some text you
  4206.              ; didn't want.
  4207.             CPUTDESC "Replace line 4 with this text." 4
  4208.              ;Alternatively, if you wanted to just kill the text on line 4
  4209.              ; that you didn't want:
  4210.             CPUTDESC "" 4
  4211.             cputrec        ;write the new description to disk
  4212.            endif
  4213.           endif
  4214.  
  4215.           You'd never get $ERRORLEVEL 1 after CPUTDESC using a technique
  4216.           similar to the above, since you've already obtained line 4, you know
  4217.           what it contains, and you're replacing it.  Really the only other
  4218.           use for CPUTDESC is to *add* text to an existing description (or to
  4219.           build an entirely new description).  In either case, you needn't
  4220.           specify a line number at all:
  4221.  
  4222.           CPUTDESC "Add this to the end of the description." 0
  4223.  
  4224.           Or simply leave the 0 off:
  4225.  
  4226.           CPUTDESC "Add this to the end of the description."
  4227.  
  4228.           TIP: To replace an entire description, use CCLEARDESC (get rid of
  4229.  
  4230.  
  4231.  
  4232.  
  4233.      Intellicomm v2.01               SCRIPT.DOC                             63
  4234.      
  4235.      
  4236.  
  4237.           the existing description) then 'CPUTDESC "new data" 0' (add the new
  4238.           one).  You can use 'CPUTDESC "new data" 0' multiple times in a loop
  4239.           (or anywhere else) if necessary, to continue adding new lines of
  4240.           text.
  4241.  
  4242.      SEE ALSO
  4243.  
  4244.       CCLEARDESC, CPUTDESC, CPUTREC
  4245.  
  4246.      EXAMPLE
  4247.  
  4248.       copen "FILELIST"
  4249.       cgetrec
  4250.  
  4251.       cputdesc "Line added complements of CPUTDESC" 0
  4252.       cputrec
  4253.  
  4254.       Please see POSTFILE.SCR for a more meaningful example of CPUTDESC.
  4255.  
  4256.      CPUTREC__________________________________________________________________
  4257.  
  4258.      SUMMARY
  4259.  
  4260.       CPUTREC [nRECNUM]
  4261.  
  4262.      DESCRIPTION
  4263.  
  4264.       Writes the current record to disk, and updates the catalog indexes if
  4265.       necessary.  CPUTREC is to be used after COPEN/CGETREC when one or more
  4266.       of the $CXXXX_FLD variables has been modified or CPUTDESC has been used.
  4267.  
  4268.       If nRECNUM is specified, it must be a valid record number for the
  4269.       currently open catalog.  Normally you'll omit nRECNUM, which simply
  4270.       updates the last record loaded by CGETREC.
  4271.  
  4272.      ERRORLEVEL
  4273.  
  4274.       0  The record was written to disk.
  4275.       1  Error updating the record.
  4276.  
  4277.      SEE ALSO
  4278.  
  4279.       CADDREC
  4280.  
  4281.      EXAMPLE
  4282.  
  4283.       copen "NEWFILES"
  4284.       cgetrec
  4285.       date2cdate $CCDATE_FLD $DATE  ;assign today's date to the Catalog Date
  4286.       cputdesc "Add this to the file description" 0
  4287.       CPUTREC     ;updates the Catalog Date, description, and all indexes
  4288.       cclose
  4289.  
  4290.      CSAVEBMARK_______________________________________________________________
  4291.  
  4292.  
  4293.  
  4294.  
  4295.      Intellicomm v2.01               SCRIPT.DOC                             64
  4296.      
  4297.      
  4298.  
  4299.      SUMMARY
  4300.  
  4301.       CSAVEBMARK [nBOOKMARK_RECNUM]
  4302.  
  4303.      DESCRIPTION
  4304.  
  4305.       Saves the current record (or nBOOKMARK_RECNUM if specified) as the
  4306.       bookmark.  The next time the user views the catalog in the File Tagger,
  4307.       the bookmarked record will be automatically hilighted.
  4308.  
  4309.      SEE ALSO
  4310.  
  4311.       CSAVESORT, CSAVEVDATE
  4312.  
  4313.      EXAMPLE
  4314.  
  4315.      CSAVESORT________________________________________________________________
  4316.  
  4317.      SUMMARY
  4318.  
  4319.       CSAVESORT
  4320.  
  4321.      DESCRIPTION
  4322.  
  4323.       Saves the current sort order, as set by CSETSORT.  The next time the
  4324.       user views the catalog (or the next time it is COPENed) the sort order
  4325.       saved by CSAVESORT will be used.
  4326.  
  4327.      SEE ALSO
  4328.  
  4329.       CSAVEBMARK, CSETSORT, CSAVEVDATE, $CSORT_DIR, $CSORT_ORDER
  4330.  
  4331.      EXAMPLE
  4332.  
  4333.       COPEN "NEWFILES"
  4334.       CSETSORT 3 1     ;sort by Filename/Date, Reversed
  4335.       CSAVESORT
  4336.       CCLOSE
  4337.  
  4338.      CSAVEVDATE_______________________________________________________________
  4339.  
  4340.      SUMMARY
  4341.  
  4342.       CSAVEVDATE [sVIEWDATE]
  4343.  
  4344.      DESCRIPTION
  4345.  
  4346.       Saves the current $VIEW_DATE (or sVIEWDATE if specified) in the catalog
  4347.       header.  The next time the user views the catalog (or the catalog is
  4348.       COPENed) the View Date saved by CSAVEVDATE will be in effect.
  4349.  
  4350.       NOTE 1: If sVIEWDATE is used, it must be specified in dBASE date format
  4351.       YYYYMMDD (YearMonthDay).  Use DATE2CDATE to convert $DATE (today's date)
  4352.       to dBASE format.
  4353.  
  4354.  
  4355.  
  4356.  
  4357.      Intellicomm v2.01               SCRIPT.DOC                             65
  4358.      
  4359.      
  4360.  
  4361.       NOTE 2: CSAVEVDATE "19800101" (January 1st, 1980) will effectively
  4362.       disable the 'View Date' feature, allowing ALL records in the catalog to
  4363.       be displayed.  No records should have a Catalog Date older than 1980.
  4364.  
  4365.      SEE ALSO
  4366.  
  4367.       CSAVEBMARK, CSAVESORT, $VIEW_DATE
  4368.  
  4369.      CSEEK____________________________________________________________________
  4370.  
  4371.      SUMMARY
  4372.  
  4373.       CSEEK [nNUMRECS] [nORIGIN]
  4374.  
  4375.      DESCRIPTION
  4376.  
  4377.       This advanced command moves the 'record pointer' of the currently open
  4378.       catalog.  The record pointer holds the record number that CGETREC will
  4379.       load next.  nNUMRECS specifies the number of records from nORIGIN to
  4380.       seek (a positive number seeks FORWARD, a negative number seeks
  4381.       BACKWARDS), nORIGIN specifies the origin of the seek as follows:
  4382.  
  4383.       0 = From the beginning of the catalog.
  4384.       1 = From the current record.
  4385.       2 = From the end of the catalog.
  4386.       3 = Seek to an absolute record number (the record number specified by
  4387.           nNUMRECS).
  4388.  
  4389.       NOTE 1: CSEEK will confuse the daylights out of you until you read the
  4390.       section "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC.  You must
  4391.       have a good grasp of the CSETSORT / CGETREC commands before using CSEEK.
  4392.  
  4393.       NOTE 2: CSEEK will be used very infrequently, and most times you'll just
  4394.       CSETSORT then CGETREC to get catalog records (CGETREC calls CSEEK 1 0
  4395.       automatically to seek to the next record).  CSEEK is provided for
  4396.       advanced use only.
  4397.  
  4398.      ERRORLEVEL
  4399.  
  4400.       0  CSEEK was successful.
  4401.       1  CSEEK was unsuccessful (no such record).
  4402.  
  4403.      SEE ALSO
  4404.  
  4405.       CTELL
  4406.  
  4407.      EXAMPLE
  4408.  
  4409.       COPEN "NEWFILES"
  4410.  
  4411.       CSETSORT -1 0     ;unsorted (no index or View Date in effect)
  4412.       CSEEK 0 2         ;seek to the end of the catalog
  4413.  
  4414.  
  4415.  
  4416.  
  4417.      Intellicomm v2.01               SCRIPT.DOC                             66
  4418.      
  4419.      
  4420.  
  4421.      CSETSORT_________________________________________________________________
  4422.  
  4423.      SUMMARY
  4424.  
  4425.       CSETSORT [nSORTORDER] [nDIRECTION]
  4426.  
  4427.      DESCRIPTION
  4428.  
  4429.       Sets the sort order and direction for the currently open catalog as
  4430.       follows:
  4431.  
  4432.       nSORTORDER:
  4433.       -1 = Unsorted
  4434.        1 = Tag Status/Location
  4435.        2 = Catalog Date/Filesize
  4436.        3 = Filename/File Date
  4437.  
  4438.       nDIRECTION:
  4439.       0 = Forward
  4440.       1 = Reversed
  4441.  
  4442.       If nSORTORDER or nDIRECTION are 0 (or omitted), CSETSORT displays a menu
  4443.       of the available sort orders / directions, and prompts the user for
  4444.       input.
  4445.  
  4446.      SEE ALSO
  4447.  
  4448.       CSAVESORT, SCRDEMO.SCR (CSETSORT is used by SCRDEMO.SCR)
  4449.  
  4450.      EXAMPLE 1
  4451.  
  4452.       COPEN "NEWFILES"
  4453.       CSETSORT      ;prompt the user for the sort order/direction
  4454.       ...
  4455.       CCLOSE
  4456.  
  4457.      EXAMPLE 2
  4458.  
  4459.       COPEN "NEWFILES"
  4460.       CSETSORT 3 0  ;sort by Filename/File Date, Forward
  4461.  
  4462.       ...
  4463.       CCLOSE
  4464.  
  4465.      CTAGALL__________________________________________________________________
  4466.  
  4467.      SUMMARY
  4468.  
  4469.       CTAGALL
  4470.  
  4471.      DESCRIPTION
  4472.  
  4473.       BETA NOTE: Command not implemented yet.
  4474.  
  4475.  
  4476.  
  4477.  
  4478.      Intellicomm v2.01               SCRIPT.DOC                             67
  4479.      
  4480.      
  4481.  
  4482.      ERRORLEVEL
  4483.  
  4484.      SEE ALSO
  4485.  
  4486.      EXAMPLE
  4487.  
  4488.      CTAGREC__________________________________________________________________
  4489.  
  4490.      SUMMARY
  4491.  
  4492.       CTAGREC [nRECNUM] [nMODE] [sBIF_ID[;sBIF_ID]...]
  4493.  
  4494.      DESCRIPTION
  4495.  
  4496.       TOGGLES the Tag status of the record specified by nRECNUM (or the
  4497.       current record if nRECNUM is 0 [zero] or omitted).  If nRECNUM is
  4498.       specified, that record number is tagged/untagged.  If nRECNUM is
  4499.       omitted, the current record (last record obtained via CGETREC) is
  4500.       tagged/untagged.
  4501.  
  4502.       Using CTAGREC is similar to highlighting a given record in Tagger browse
  4503.       mode and selecting "Tag".  I.e. if the record is Tagged and you CTAGREC
  4504.       it, it becomes untagged.  If the record is untagged and you CTAGREC it,
  4505.       it becomes Tagged.  It works a little differently if working with the
  4506.       FILELIST (upload) catalog, however.  See below.
  4507.  
  4508.       [nMODE] and [sBIF_ID[;sBIF_ID]...] are only valid if the FILELIST
  4509.       (upload) catalog is open, and they are used to add the "Upload Pending"
  4510.       strings you see in the File Tagger after you Tag a file for uploading. 
  4511.       If sBIFID is blank ("") then all Upload Pending BIFID's are removed from
  4512.       the record, and the record is untagged.  If one or more BIFID's are
  4513.       specified (in the format "BIFID" or "BIFID1;BIFID2;BIFID3"...etc) then
  4514.       nMODE comes into play as follows:
  4515.  
  4516.        nMODE = -1  the passed BIFID(s) are removed from ULPEND (if found).
  4517.        nMODE =  0  the passed BIFID(s) replace the existing ones.
  4518.        nMODE =  1  the passed BIFID(s) are appended to the existing ULPEND.
  4519.  
  4520.       See the example for details.
  4521.  
  4522.      ERRORLEVEL
  4523.  
  4524.       0  CTAGREC was successful.
  4525.       1  Unable to load nRECNUM (if specified).
  4526.       2  The current record (or nRECNUM) is marked as "deleted".  Deleted
  4527.          records cannot be tagged/untagged.  This errorlevel is returned only
  4528.          to eliminate confusion: you should never "undelete" a deleted record
  4529.          to Tag it.  If the record is deleted, either the user deleted it for
  4530.          a reason; or Icom has already successfully downloaded the file.
  4531.       3  Unable to switch the Tag status (likely a disk write error).  If you
  4532.          get this error, try a CPACK to rebuild the indexes.
  4533.  
  4534.      SEE ALSO
  4535.  
  4536.  
  4537.  
  4538.  
  4539.      Intellicomm v2.01               SCRIPT.DOC                             68
  4540.      
  4541.      
  4542.  
  4543.       CNOTEREC
  4544.  
  4545.      EXAMPLE 1
  4546.  
  4547.       copen "newfiles"
  4548.       cgetrec
  4549.       CTAGREC
  4550.       cclose
  4551.  
  4552.      EXAMPLE 2
  4553.  
  4554.        ;Tagging files for upload is only useful to have Icom itself upload
  4555.        ; the files (i.e. using the PREJOB.SCR to Tag files for upload prior
  4556.        ; to an automated job that had one or more "Upload tagged files"
  4557.        ; tasks). Uploading files (handling the entire process) from a script
  4558.        ; and trying to use the FILELIST catalog would be a very complex
  4559.        ; procedure, and it is not recommended.
  4560.  
  4561.       copen "filelist"      ;open the upload catalog
  4562.       cgetrec
  4563.       CTAGREC 0 1 "JOESBBS" ;tag for uploading to joesbbs... if JOESBBS
  4564.                             ; already exists in the "Upload Pending" string,
  4565.                             ; no action is taken.  If JOESBBS doesn't exist,
  4566.                             ; it is appended (Upload Pending:ABBS;JOESBBS).
  4567.  
  4568.       CTAGREC 0 -1 "JOESBBS" ;JOESBBS is removed from the "Upload Pending"
  4569.                              ; string if it exists.  If no more BIFID's remain
  4570.                              ; in the Upload Pending string, the record is
  4571.                              ; also automatically Untagged.
  4572.       CTAGREC 0 0 "JOESBBS"  ;all other BIFID's in the Upload Pending string
  4573.                              ; (if any) are removed, and JOESBBS is added.
  4574.  
  4575.  
  4576.       CTAGREC 0 0 ""         ;all BIFID's are removed from the Upload Pending
  4577.                              ; string, none are added, and the record is
  4578.                              ; Untagged
  4579.       cclose
  4580.  
  4581.      CTELL____________________________________________________________________
  4582.  
  4583.      SUMMARY
  4584.  
  4585.       CTELL vCUR_REC
  4586.  
  4587.      DESCRIPTION
  4588.  
  4589.       Stores the record number of the currently loaded record in variable
  4590.       vCUR_REC (a user-defined variable, defined using the VARIABLE command). 
  4591.       CTELL is useful for saving your position in a catalog.  Use CTELL to get
  4592.       the current record number, then use CSEEK vCUR_REC 3 (seek to absolute
  4593.       record number) to seek back to it later.
  4594.  
  4595.       NOTE: You must use CTELL before using CDELREC (delete a catalog record),
  4596.       since you must specify a record number with CDELREC.
  4597.  
  4598.  
  4599.  
  4600.  
  4601.      Intellicomm v2.01               SCRIPT.DOC                             69
  4602.      
  4603.      
  4604.  
  4605.      EXAMPLE
  4606.  
  4607.       variable recnum
  4608.       copen "NEWFILES"
  4609.       CTELL recnum     ;store current position in 'recnum'
  4610.       ...              ;CGETREC and otherwise fiddle around
  4611.       cseek recnum 3   ;seek back to original position
  4612.       ...              ;do whatever needs doing
  4613.       CCLOSE
  4614.  
  4615.      SEE ALSO
  4616.  
  4617.  
  4618.      CURSORLARGE______________________________________________________________
  4619.      CURSORSMALL______________________________________________________________
  4620.  
  4621.      SUMMARY
  4622.  
  4623.       CURSORLARGE
  4624.       CURSORSMALL
  4625.  
  4626.      DESCRIPTION
  4627.  
  4628.       CURSORLARGE changes the cursor to large (half character height) while
  4629.       CURSORSMALL changes the cursor to small (underline).  If the cursor is
  4630.       hidden (CURSOROFF, etc) when either command is called, it will be re-
  4631.       displayed.  Note that the BOXGETS and GETS/GETSXY commands do not use
  4632.       the current cursor size, and they display the cursor as large/small
  4633.       according to the current Insert/Typeover status set by the user.
  4634.  
  4635.      SEE ALSO
  4636.  
  4637.       CURSORPOP, CURSORPUSH, CURSOROFF, CURSORON
  4638.  
  4639.      EXAMPLE
  4640.  
  4641.       CURSORLARGE
  4642.       pause "Press a key... "
  4643.       CURSORSMALL
  4644.  
  4645.      CURSOROFF________________________________________________________________
  4646.      CURSORON_________________________________________________________________
  4647.  
  4648.      SUMMARY
  4649.  
  4650.       CURSOROFF
  4651.       CURSORON
  4652.  
  4653.      DESCRIPTION
  4654.  
  4655.       CURSOROFF hides the screen cursor, while CURSORON re-displays a hidden
  4656.       screen cursor.
  4657.  
  4658.      SEE ALSO
  4659.  
  4660.  
  4661.  
  4662.  
  4663.      Intellicomm v2.01               SCRIPT.DOC                             70
  4664.      
  4665.      
  4666.  
  4667.       CURSORONOFF, CURSORPUSH, CURSORPOP
  4668.  
  4669.      EXAMPLE
  4670.  
  4671.  
  4672.      CURSOROFF
  4673.      pause "Press any key to continue..."
  4674.      CURSORON
  4675.  
  4676.      CURSORONOFF______________________________________________________________
  4677.  
  4678.      SUMMARY
  4679.  
  4680.       CURSORONOFF nSTATE
  4681.  
  4682.      DESCRIPTION
  4683.  
  4684.       Turns the cursor on or off, according to nSTATE.  If nSTATE is 0 (zero)
  4685.       the cursor is turned off (hidden).  If nSTATE is non-zero the cursor is
  4686.       turned on (unhidden).
  4687.  
  4688.      SEE ALSO
  4689.  
  4690.       CURSORON, CURSOROFF
  4691.  
  4692.      EXAMPLE
  4693.  
  4694.       pause "Press a key to hide the cursor..."
  4695.       CURSORONOFF 0
  4696.  
  4697.       pause "Press a key to unhide the cursor..."
  4698.       CURSORONOFF 1
  4699.  
  4700.      CURSORPOP________________________________________________________________
  4701.      CURSORPUSH_______________________________________________________________
  4702.  
  4703.      SUMMARY
  4704.  
  4705.       CURSORPOP
  4706.       CURSORPUSH [nNEWSTATUS]
  4707.  
  4708.      DESCRIPTION
  4709.  
  4710.       CURSORPUSH saves the position (screen x/y coordinate), size, and on/off
  4711.       status of the cursor, and optionally sets a new on/off status.  If
  4712.       nNEWSTATUS is omitted, the cursor status (on/off) remains unchanged
  4713.       after CURSORPUSH.  If nNEWSTATUS is specified, a value of -1 means to
  4714.       leave the cursor status as is (same as not specifying it) while a value
  4715.       of 0 (zero) means to turn the cursor off (same as CURSOROFF) while a
  4716.       value of 1 (one) means to turn the cursor on (same as CURSORON).
  4717.  
  4718.       You can call CURSORPUSH up to 16 times (if necessary, saving different
  4719.       cursor states/positions) before calling CURSORPOP.  If you call
  4720.       CURSORPUSH 17 times without a single CURPOP, you'll get a CURSORPUSH
  4721.  
  4722.  
  4723.  
  4724.  
  4725.      Intellicomm v2.01               SCRIPT.DOC                             71
  4726.      
  4727.      
  4728.  
  4729.       Stack Overflow error and your script will abort.
  4730.  
  4731.       CURSORPOP restores the cursor to the location, size and on/off status it
  4732.       had before the *last* CURSORPUSH (last in, first out).
  4733.  
  4734.      SEE ALSO
  4735.  
  4736.       CURSORON, CURSOROFF
  4737.  
  4738.      EXAMPLE
  4739.  
  4740.      vpush        ;save contents of the video screen
  4741.      CURSORPUSH   ;save cursor state
  4742.      cursoron     ;turn cursor on
  4743.      cursorlarge  ;large cursor
  4744.      cls          ;clear screen, GOTOXY 1 1   
  4745.      pause "Press a key to restore..."
  4746.      vpop
  4747.      curpop
  4748.      pause "Back to normal..."
  4749.  
  4750.  
  4751.      DATE2CDATE_______________________________________________________________
  4752.  
  4753.      SUMMARY
  4754.  
  4755.       DATE2CDATE vCDATE sDATE
  4756.  
  4757.      DESCRIPTION
  4758.  
  4759.       Converts sDATE (a date in the format returned by $DATE or $FDATE) to a
  4760.       dBASE style date (YYYYMMDD) and stores in vCDATE.
  4761.  
  4762.      ERRORLEVEL
  4763.  
  4764.       0  sDATE contained a valid date, and it has been converted and stored in
  4765.          vCDATE.
  4766.       1  sDATE is not a valid date, and vCDATE is empty.
  4767.  
  4768.      SEE ALSO
  4769.  
  4770.       CDATE2DATE
  4771.  
  4772.      EXAMPLE 1
  4773.  
  4774.       CGETREC
  4775.       DATE2CDATE $CCDATE_FLD $DATE  ;assign today's date to Catalog Date
  4776.       CPUTREC
  4777.  
  4778.      EXAMPLE 2
  4779.  
  4780.       DATE2CDATE $VIEW_DATE $DATE   ;assign today's date to View Date
  4781.       CSAVEVDATE                    ;save in catalog header
  4782.  
  4783.  
  4784.  
  4785.  
  4786.      Intellicomm v2.01               SCRIPT.DOC                             72
  4787.      
  4788.      
  4789.  
  4790.      DEBUG____________________________________________________________________
  4791.  
  4792.      SUMMARY
  4793.  
  4794.       DEBUG nSTAT | vVARIABLE
  4795.  
  4796.      DESCRIPTION
  4797.  
  4798.       | above means 'OR'.  You can use 0, 1, 2 (nSTAT), OR a variable name
  4799.       (vVARIABLE).  The script debugger is explained in detail in
  4800.       SCRTUTOR.DOC.
  4801.  
  4802.       DEBUG 0 turns debugging off, DEBUG 1 turns step-by-step debugging on,
  4803.       DEBUG 2 turns 'animated' debugging mode on.  A variable name, if
  4804.       specified, pauses the script and displays the contents of the variable. 
  4805.       All can be very useful in finding script logic errors.
  4806.  
  4807.      EXAMPLE
  4808.  
  4809.       variable count
  4810.  
  4811.       DEBUG 2           ;turn 'animate' mode on... displays each script line
  4812.                         ; on the status line at the rate of two lines per
  4813.                         ; second, prior to executing the line.
  4814.       assign count 0
  4815.       while count < 10
  4816.        inc count
  4817.       endwhile
  4818.  
  4819.       DEBUG count      ;displays the contents of 'count' (would be 10)
  4820.  
  4821.       DEBUG 1          ;turn 'step-by-step' debugging on... displays each
  4822.                        ; script line on the status line, then pauses until
  4823.                        ; you press [Space] or [Enter] before executing the
  4824.                        ; line.
  4825.  
  4826.       while count < 10 ;this displays "WHILE 10 < 10" (the variable's value is
  4827.        inc count       ; displayed, rather than showing the variable name).
  4828.       endwhile
  4829.       
  4830.       DEBUG 0          ;turn debug mode off.
  4831.       return
  4832.       
  4833.      DEC______________________________________________________________________
  4834.  
  4835.      SUMMARY
  4836.  
  4837.       DEC vNUM
  4838.  
  4839.      DESCRIPTION
  4840.  
  4841.       Subtracts 1 from the contents of the specified variable vNUM.  If the
  4842.       variable contained the number 10, DEC would decrement it to 9.  If the
  4843.       variable contained 0, DEC would changes it to -1.  If the variable
  4844.  
  4845.  
  4846.  
  4847.  
  4848.      Intellicomm v2.01               SCRIPT.DOC                             73
  4849.      
  4850.      
  4851.  
  4852.       contained TEXT instead of a number, iot will contain -1 when DEC
  4853.       finishes with it (since 0 is assumed if vNUM is missing, or if it's non-
  4854.       numeric).  DEC first converts the variable to a number (text translates
  4855.       to the number 0), then subtracts 1 from that number.
  4856.  
  4857.      SEE ALSO
  4858.  
  4859.       ADD, SUB, INC
  4860.  
  4861.      EXAMPLE
  4862.       
  4863.       variable count 10  ;define variable 'count', assign 10 to it
  4864.  
  4865.       ;count from 10 down to 1
  4866.  
  4867.       while count > 0    ;while count is greater than 0, do to endwhile
  4868.        print count       ;print the contents of 'count'
  4869.        DEC count         ;count = count - 1
  4870.       endwhile
  4871.  
  4872.      DELAY____________________________________________________________________
  4873.      _ 
  4874.      SUMMARY
  4875.  
  4876.       DELAY nTENTHS
  4877.  
  4878.      DESCRIPTION
  4879.  
  4880.       Delays execution of the script for nTENTHS tenths of a second.  So to
  4881.       delay for one second you'd use DELAY 10, to delay for a minute you'd use
  4882.       DELAY 600, and so forth.
  4883.  
  4884.       NOTE: DELAY updates the terminal screen with incoming characters from
  4885.       the BBS while paused.  To pause and freeze the display, use DELAYNC.
  4886.  
  4887.      SEE ALSO
  4888.  
  4889.       DELAYNC, PAUSE, WAITUNTIL
  4890.  
  4891.      EXAMPLE
  4892.  
  4893.       send "D"            ;send a [D]ownload command to the BBS
  4894.       delay 10            ;pause for a second to wait for the filename prompt
  4895.       send "ICOM201A.ZIP"
  4896.       delay 50            ;wait 5 seconds for the D/L to start
  4897.       download "Z"        ;download using Zmodem
  4898.  
  4899.      DELAYNC__________________________________________________________________
  4900.  
  4901.      SUMMARY
  4902.  
  4903.       DELAYNC nTENTHS
  4904.  
  4905.      DESCRIPTION
  4906.  
  4907.  
  4908.  
  4909.  
  4910.      Intellicomm v2.01               SCRIPT.DOC                             74
  4911.      
  4912.      
  4913.  
  4914.       Delays execution of the script for nTENTHS tenths of a second.  So to
  4915.       delay for one second you'd use DELAYNC 10, to delay for a minute you'd
  4916.       use DELAYNC 600.
  4917.  
  4918.       NOTE: The NC in DELAYNC stands for 'N'o 'C'omm. updating.  DELAYNC does
  4919.       NOT update the terminal screen with incoming characters from the BBS
  4920.       during the delay.  To allow incoming characters to be displayed during a
  4921.       delay, use the DELAY command.  You won't actually lose any characters
  4922.       from the BBS during a DELAYNC; Icom's interrupt handler is still getting
  4923.       characters from the COM port and storing them in its internal buffer
  4924.       (which defaults to 4 kilobytes in size).  It just doesn't update the
  4925.       terminal screen with the incoming characters.
  4926.  
  4927.      SEE ALSO
  4928.  
  4929.       DELAY, PAUSE, WAITUNTIL
  4930.  
  4931.      EXAMPLE
  4932.  
  4933.       ;^M^J is carriage return/line feed (move to a new line)
  4934.       print "^M^JNOTE: <some important message>"
  4935.  
  4936.      DEL___________________________________________________________________
  4937.      DELETE________________________________________________________________
  4938.  
  4939.      SUMMARY
  4940.  
  4941.       DEL    sFILESPEC
  4942.       DELETE sFILESPEC
  4943.       
  4944.      DESCRIPTION
  4945.  
  4946.       Similar to the DOS 'DEL' and 'DELETE' commands, this script command
  4947.       deletes a specified filespec from the disk.  You are allowed to use
  4948.       wildcards (*, ?) in the filespec portion if necessary.  You cannot
  4949.       delete directories with the DELETE command (use RMDIR to delete
  4950.       directories).
  4951.  
  4952.       You may omit the drive and/or directory in sFILESPEC if the file(s) to
  4953.       be deleted are in the current DOS directory ($CURDIR), but if you use
  4954.       this method make sure you KNOW which directory you're in first by using 
  4955.       CHDIR.  Icom changes directories for various purposes during its course
  4956.       of operation, and you really can never be sure which directory you're in
  4957.       when your script is running, unless you check $CURDIR or use CHDIR at
  4958.       some point before the DELETE command.
  4959.  
  4960.       WARNING: Do not attempt to delete a file that is currently 'open' with
  4961.       the FOPEN command or CAPTURE command.  It can cause sharing violations
  4962.       and/or exception 13's.  You must CCLOSE (catalogs, if you COPENed one)
  4963.       FCLOSE (regular files, if you FOPENed the file) or CAPCLOSE (the capture
  4964.       file) before deleting them.
  4965.  
  4966.      ERRORLEVEL
  4967.  
  4968.  
  4969.  
  4970.  
  4971.      Intellicomm v2.01               SCRIPT.DOC                             75
  4972.      
  4973.      
  4974.  
  4975.       0  File(s) successfully deleted.
  4976.       1  Error deleting one or more files (file not found, or the file's "read
  4977.          only" attribute is set).  $ERRORLEVEL can be above 1 (2,3,4,etc) if
  4978.          more than one error occurs ... it is set to the number of files that
  4979.          could not be deleted.
  4980.  
  4981.      SEE ALSO
  4982.  
  4983.       DISKFIND, DOS, EXIST, LOCATEFILE, NOTEXIST, RENAME, RENUMBER, RMDIR
  4984.  
  4985.      EXAMPLE
  4986.  
  4987.       ;CAPTURE always appends (adds to the end) of existing files.  If
  4988.       ; you wish to create a new capture file, simply DELETE the existing
  4989.       ; file prior to calling CAPTURE.
  4990.       
  4991.       CAPCLOSE                     ;always make sure it's closed...
  4992.       DELETE "\ICOM\CAP\ICOM.CAP"  ;or use DELETE $CAP_NAME
  4993.       CAPTURE "\ICOM\CAP\ICOM.CAP" ;or use CAPTURE $CAP_NAME
  4994.       
  4995.      DIAL_____________________________________________________________________
  4996.  
  4997.      SUMMARY
  4998.  
  4999.       DIAL [sBBSNAME] [nEXACTMATCH]
  5000.  
  5001.      DESCRIPTION
  5002.  
  5003.       Dials one or more BIFs, or a specific telephone number, or displays the
  5004.       BBS Directory for user input.
  5005.  
  5006.       Variation 1, dialing one or more BIFs:
  5007.  
  5008.       If sBBSNAME is specified and nEXACTMATCH is omitted, DIAL switches to
  5009.       the BBS Directory (the equivalent of pressing [Alt-D] in Icom), selects
  5010.       "Find" from the BBS Directory menu, enters sBBSNAME, then selects "Find
  5011.       all/Tag all".  Any/all BIFs matching sBBSNAME are then tagged and
  5012.       dialed. If nEXACTMATCH is specified (as a non-zero number) then "Find
  5013.       all/Tag all" is NOT in effect and only one BIF is tagged: its
  5014.       description must match sBBSNAME exactly.
  5015.  
  5016.       Variation 2, dialing a specific telephone number:
  5017.  
  5018.       If sBBSNAME contains "^M" as its first character, a specific telephone
  5019.       number is dialed (similar to selecting "Manual" from the BBS Directory;
  5020.       e.g. DIAL "^M555-1234").
  5021.  
  5022.       Variation 3, manual user input:
  5023.  
  5024.       If both sBBSNAME and NEXACTMATCH are omitted, the BBS Directory is
  5025.       displayed for manual user input (the same as pressing [Alt-D]).
  5026.  
  5027.       Only when DIAL connects (or aborts due to an error) does your script
  5028.       continue running.  If multiple BBS's are tagged (when not specifying
  5029.  
  5030.  
  5031.  
  5032.  
  5033.      Intellicomm v2.01               SCRIPT.DOC                             76
  5034.      
  5035.      
  5036.  
  5037.       nEXACTMATCH or a manual number) you can check the $BIF_NAME System
  5038.       Variable when DIAL returns, to see which bulletin board you are
  5039.       connected to.
  5040.  
  5041.       NOTE: Using the DIAL or REDIAL commands cause any previously defined
  5042.       WHEN commands to be lost.  All WHENs are cleared when DIAL exits.
  5043.  
  5044.       TIP: You can use a single character as the sBBSNAME parameter if you
  5045.       like.  By placing specific characters in your BIF descriptions (@, !, #,
  5046.       etc) you could set up a system whereby different groups of BIFs could be
  5047.       dialed under different circumstances.  You could dial one set on
  5048.       weekdays by putting, say, ! in the descriptions of the BIFs you want to
  5049.       dial on weekdays, then using DIAL "!".  You could dial another set on
  5050.       weekends by placing @ in those descriptions then using DIAL "@".  The
  5051.       $DOW (Day Of Week) System Variable will tell your script what day it is. 
  5052.       You could also place multiple symbols in some BIFs (!@) to have certain
  5053.       BIFs dialed on both weekdays and weekends, etc.  The same sort of thing
  5054.       can be done using the time of day ($HOUR, $MIN, $SEC) or day of month
  5055.       ($DAY) to have various BBS's called at certain times of the day, or on
  5056.       certain days of the month.
  5057.  
  5058.       Regardless of how DIAL is used, the $ERRORLEVEL System Variable is set
  5059.       to 0 if dialing is successful and a connection is established.  At that
  5060.       point it's up to your script to perform the logon.  If you'd rather have
  5061.       Icom perform the logon (to take advantage of the BIF, and possible
  5062.       logons through the PC-Pursuit or iNet long-distance services), then you
  5063.       shouldn't use a DIAL command in your script.  Rather you should define a
  5064.       job such as this:
  5065.  
  5066.         Call <some BBS>
  5067.           CC: @MYSCRIPT
  5068.           Send message replies
  5069.           ...etc.
  5070.  
  5071.       I.e. use an automated job to perform the dialing/logon, then run your
  5072.       script via the "Custom Command" task.  Icom will take care of both the
  5073.       logon and logoff in these cases, assuming the BIF is set properly.  If
  5074.       possible, when using Custom Commands to execute scripts, you should have
  5075.       your script return to one of the BBS 'main' menus before it exits and
  5076.       returns control to Intellicomm (the Main Menu A, Main Menu B, Message
  5077.       Menu, Bank Menu, or File Menu prompt).  Icom does perform a check of the
  5078.       current BBS prompt after Custom Commands to locate its position, but if
  5079.       you leave it in an area of the BBS that it isn't familiar with (i.e. a
  5080.       DOOR or sub-menu other than one of the menus mentioned above) it may not
  5081.       be able to get back to a menu it recognizes, and thus may be forced to
  5082.       disconnect and call back, wasting online time (though your script would
  5083.       not be executed after the call-back; jobs are flagged as 'complete' when
  5084.       they finish).
  5085.  
  5086.      ERRORLEVEL
  5087.  
  5088.       0  Dial/connection successful.
  5089.       1  No connection (the user may have pressed the [Esc] key, or the number
  5090.          may have been tried to the "Max. Redials" for the BIF, and too many
  5091.  
  5092.  
  5093.  
  5094.  
  5095.      Intellicomm v2.01               SCRIPT.DOC                             77
  5096.      
  5097.      
  5098.  
  5099.          other possibilities to list... but you didn't get connected).
  5100.       2  A "Search String" was specified, but no matches were found in any of
  5101.          the BIF descriptions.  If this happens Icom also displays a status
  5102.          window stating "Text not found".
  5103.  
  5104.       The easiest way to check whether DIAL was successful is to use the
  5105.       OFFLINE command after DIAL to check the connect status.  Example:
  5106.  
  5107.       DIAL "My Favorite BBS" 1
  5108.       offline exit              ;exit the script if offline
  5109.  
  5110.      SEE ALSO
  5111.  
  5112.       REDIAL
  5113.  
  5114.      EXAMPLE
  5115.  
  5116.       DIAL "Joe's BBS"
  5117.       if $ERRORLEVEL <> 0 return  ;exit if $ERRORLEVEL is not equal to 0
  5118.       when "Name?" send "John Smith"
  5119.       when "Password?" send "mypassword"
  5120.       waitfor "Selection:" 60
  5121.       return                      ;leaves the user in Manual Terminal mode if
  5122.                                   ; online when the script ends
  5123.  
  5124.      ADVANCED EXAMPLE
  5125.  
  5126.       DIAL "BBS"         ;tags/dials ALL BIFs with 'BBS' in their descriptions
  5127.       while 1            ;enter an endless loop (until BREAK)
  5128.        switch $BIF_NAME  ;check which BIF 'DIAL' connected to
  5129.         case "JOESBBS"
  5130.          gosub handle_joes_bbs
  5131.         endcase
  5132.         case "THEBBS"
  5133.          gosub handle_the_bbs
  5134.         endcase
  5135.         ;subroutines not given... It is assumed they would perform the
  5136.         ; logon/online session/logoff then RETURN for the redial
  5137.        endswitch
  5138.        hangup
  5139.        redial         ;dial any BIFs still tagged
  5140.        offline break  ;exit loop if not connected (nothing left to dial)
  5141.       endwhile
  5142.  
  5143.      DIREXIST_________________________________________________________________
  5144.  
  5145.      SUMMARY
  5146.  
  5147.       DIREXIST sDIRECTORY_NAME cCOMMAND
  5148.  
  5149.      DESCRIPTION
  5150.  
  5151.       Executes cCOMMAND if sDIRECTORY_NAME (a \DIRECTORY\SUBDIR or
  5152.       D:\DIRECTORY\, etc) exists; skips cCOMMAND if sDIRECTORY_NAME does not
  5153.  
  5154.  
  5155.  
  5156.  
  5157.      Intellicomm v2.01               SCRIPT.DOC                             78
  5158.      
  5159.      
  5160.  
  5161.       exist.
  5162.  
  5163.      SEE ALSO
  5164.  
  5165.       EXIST, NOTEXIST, FINDFIRST, FINDNEXT
  5166.  
  5167.      EXAMPLE
  5168.  
  5169.       DIREXIST $DL_DIR goto start
  5170.       mkdir $DL_DIR
  5171.      start:
  5172.  
  5173.      DISKFIND_________________________________________________________________
  5174.  
  5175.      SUMMARY
  5176.  
  5177.       DISKFIND vFILEFOUND sFILESPEC ...
  5178.  
  5179.      DESCRIPTION
  5180.  
  5181.       Searches the specified disk drive for sFILESPEC in the format
  5182.       D:FILENAME.EXT.  If a file is found matching the filespec its full
  5183.       pathname (D:\PATH\FILENAME.EXT) is stored in vFILEFOUND.
  5184.  
  5185.       sFILESPEC may contain wildcards (*, ?) and the disk drive is optional. 
  5186.       If no disk drive is specified the current drive is assumed.  Directory
  5187.       names (\PATH\) should not be specified in sFILESPEC, as the purpose of
  5188.       DISKFIND is to locate a file when you DON'T know which directory the
  5189.       file is in.  Every directory on the drive is searched and thus you
  5190.       simply give DISKFIND a filename (or filespec such as "C:ICOM*.*"). 
  5191.       Directories will be ignored if specified.
  5192.  
  5193.       The search begins at the root directory of the drive and traverses
  5194.       through directories and subdirectories as they are encountered.
  5195.  
  5196.      ERRORLEVEL
  5197.  
  5198.       0  The file was found and its full pathname is stored in vFILEFOUND.
  5199.       1  The file was not found (vFILEFOUND is empty).
  5200.       2  An invalid drive was specified (vFILEFOUND is empty).
  5201.  
  5202.      SEE ALSO
  5203.  
  5204.       LOCATEFILE
  5205.  
  5206.      EXAMPLE
  5207.  
  5208.       variable findme "*.DBF"  ;define variable 'findme' assign *.DBF to it
  5209.  
  5210.       DISKFIND findme findme   ;you can store the result in the same variable
  5211.  
  5212.       if $ERRORLEVEL = 0
  5213.        print "Found a dBASE database (or Icom File Tagger catalog):"
  5214.        print findme
  5215.  
  5216.  
  5217.  
  5218.  
  5219.      Intellicomm v2.01               SCRIPT.DOC                             79
  5220.      
  5221.      
  5222.  
  5223.       else
  5224.        msgwind "*.DBF not found"
  5225.       endif
  5226.  
  5227.  
  5228.  
  5229.      DISKFREE_________________________________________________________________
  5230.  
  5231.      SUMMARY
  5232.  
  5233.       DISKFREE vBYTESFREE [sDRIVE]
  5234.  
  5235.      DESCRIPTION
  5236.  
  5237.       Places the number of free bytes available on drive sDRIVE in vBYTESFREE. 
  5238.       If sDRIVE is omitted the current drive is assumed.
  5239.  
  5240.      ERRORLEVEL
  5241.  
  5242.       None.  If sDRIVE is invalid, vBYTESFREE is set to -1 (minus one).
  5243.  
  5244.      EXAMPLE
  5245.  
  5246.       variable cfree
  5247.       DISKFREE cfree "C"  ;the colon (C:) is not needed
  5248.       print "Drive C: has " cfree " bytes free."
  5249.  
  5250.      DIV______________________________________________________________________
  5251.  
  5252.      SUMMARY
  5253.  
  5254.       DIV vQUOTIENT nDIVIDEND nDIVISOR
  5255.  
  5256.      DESCRIPTION
  5257.  
  5258.       Divides nDIVIDEND by nDIVISOR and stores the result (rounded; no
  5259.       remainder) in vQUOTIENT.
  5260.  
  5261.      SEE ALSO
  5262.  
  5263.       ADD, MUL, SUB
  5264.  
  5265.      EXAMPLE
  5266.  
  5267.       variable result
  5268.       ADD result 10 5   ;stores 10 divided by 5 (2) in variable 'result'
  5269.       print result
  5270.  
  5271.      DOS______________________________________________________________________
  5272.  
  5273.      SUMMARY
  5274.  
  5275.       DOS [sCOMMAND ...]
  5276.  
  5277.  
  5278.  
  5279.  
  5280.      Intellicomm v2.01               SCRIPT.DOC                             80
  5281.      
  5282.      
  5283.  
  5284.      DESCRIPTION
  5285.  
  5286.       Executes an external program.  If sCOMMAND is omitted a DOS shell is
  5287.       performed (the same as pressing [Alt-J]).  The DOS command calls
  5288.       COMMAND.COM to executed sCOMMAND and thus batch files (.BAT) can be
  5289.       executed, and redirection (>, >>, <) and/or pipes (|) can be used in the
  5290.       command no different than if you were sitting at the C:> prompt.
  5291.  
  5292.       NOTE: Intellicomm will swap itself out of base memory before executing
  5293.       sCOMMAND depending upon the setting of the *swpon (Swap On) System
  5294.       Variable defined by the user in the main setup:
  5295.  
  5296.        *swpon = 0   No swapping
  5297.        *swpon = 1   When not connected
  5298.        *swpon = 2   Connected or not
  5299.  
  5300.       See the System Variables section below for more information on *swpon.
  5301.  
  5302.       To force a Swap regardless of the setting of *swpon specify "SW:" as the
  5303.       first item in sCOMMAND.  To force NO swapping regardless of the setting
  5304.       of *swpon specify "NS:" as the first item in sCOMMAND.  See the example
  5305.       for details.
  5306.  
  5307.      ERRORLEVEL
  5308.  
  5309.       -3  Not enough memory to load COMMAND.COM.
  5310.       -2  No file handles to open COMMAND.COM (increase FILES= in CONFIG.SYS).
  5311.       -1  COMMAND.COM could not be located.
  5312.        0+ (Zero or greater) COMMAND.COM was located and executed.  Whether the
  5313.           DOS sCOMMAND was carried out successfully cannot be determined as
  5314.           COMMAND.COM does not return an errorlevel to indicate external
  5315.           program errors.  Use the EXEC command when you must determine the
  5316.           exit code of a program.
  5317.  
  5318.      SEE ALSO
  5319.  
  5320.       EXEC
  5321.  
  5322.      EXAMPLE
  5323.  
  5324.       DOS               ;DOS shell, swapping determined by *swpon
  5325.       DOS "SW:"         ;DOS shell, force Icom to swap out
  5326.       DOS "NS:"         ;DOS shell, force Icom NOT to swap out
  5327.  
  5328.       DOS "123.EXE"     ;COMMAND.COM seaches the PATH for 123.EXE and executes
  5329.                         ; it if found.  *swpon determines swapping.
  5330.       DOS "NS:LIST.COM" ;Execute LIST.COM, do not swap out.
  5331.  
  5332.       DOS "SW:C:\BAT\DELUXE.BAT"  ;Execute C:\BAT\DELUXE.BAT, swap out first
  5333.  
  5334.       DOS "DIR > DIRLIST.TXT"     ;Execute a 'DIR'ectory command, redirect
  5335.                                   ; output to a file called DIRLIST.TXT
  5336.  
  5337.        ;Get user input and execute the command
  5338.  
  5339.  
  5340.  
  5341.  
  5342.      Intellicomm v2.01               SCRIPT.DOC                             81
  5343.      
  5344.      
  5345.  
  5346.       variable command
  5347.       boxgets command "DOS Command" "Enter a DOS command to execute" 64
  5348.       dos command
  5349.  
  5350.      DOWNLOAD_________________________________________________________________
  5351.  
  5352.      SUMMARY
  5353.  
  5354.       DOWNLOAD sPROTOCOL [sFILENAME]
  5355.  
  5356.      DESCRIPTION
  5357.  
  5358.       Downloads sFILENAME (if specified) using transfer protocol sPROTOCOL. 
  5359.       sFILENAME is required by the protocols which have an asterisk following
  5360.       their name below.  sFILENAME can be specified for protocols which do not
  5361.       require a filename to be specified (Ymodem/Zmodem): if you pass a
  5362.       filename to these protocols, the first file accepted will use the
  5363.       filename you specify.  Normally you will not specify sFILENAME when
  5364.       calling Ymodem or Zmodem, since the proper filename is passed by the
  5365.       sending protocol, but it can be useful to 'force' a specific filename
  5366.       under some circumstances.
  5367.  
  5368.       sPROTOCOL is the 'hotkey' used to select the protocol from the protocol
  5369.       menu from Terminal Mode (including external protocols, if any are
  5370.       installed):
  5371.  
  5372.       "A" = ASCII*
  5373.       "R" = Relaxed Xmodem*
  5374.       "X" = Xmodem*
  5375.       "1" = Xmodem-1K*
  5376.       "K" = Xmodem-1K-G*
  5377.       "Y" = Ymodem
  5378.       "G" = Ymodem-G
  5379.       "Z" = Zmodem
  5380.  
  5381.       NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols.  This
  5382.       means that they can download several files using a single DOWNLOAD
  5383.       command.
  5384.  
  5385.      ERRORLEVEL
  5386.  
  5387.       0  Transfer successful (if batch, all files were downloaded)
  5388.       1  User abort ([Esc] pressed)
  5389.       2  Connection lost
  5390.       3  Remote (BBS protocol) cancelled
  5391.       4  Disk read/write error
  5392.       5  Bad external protocol (if called an external and not found)
  5393.       6  Flow control error (not relevant to DOWNLOAD, only UPLOAD)
  5394.       7  Miscellaneous protocol error (too many timeouts, etc).
  5395.  
  5396.      SEE ALSO
  5397.  
  5398.       UPLOAD
  5399.  
  5400.  
  5401.  
  5402.  
  5403.      Intellicomm v2.01               SCRIPT.DOC                             82
  5404.      
  5405.      
  5406.  
  5407.      EXAMPLE 1
  5408.  
  5409.       variable filename
  5410.  
  5411.       assign filename "FILENAME.ZIP"  ;some filename to download
  5412.       send "D " filename              ;tell BBS to download
  5413.       waitfor "(Ctrl-X) Aborts"       ;wait for 'begin transfer' prompt
  5414.       DOWNLOAD "1" filename           ;Download FILENAME.ZIP using Xmodem-1K
  5415.  
  5416.      EXAMPLE 2
  5417.  
  5418.       send "D FILE1.ZIP FILE2.ZIP FILE3.ZIP Z" ;PCBoard (and others) Download
  5419.                                                ; several files using Zmodem
  5420.       waitfor "(Ctrl-X) Aborts"
  5421.       DOWNLOAD "Z"                    ;Download one or more files using Zmodem
  5422.  
  5423.      EDIT_____________________________________________________________________
  5424.  
  5425.      SUMMARY
  5426.  
  5427.       EDIT [sFILENAME] [nLINENUM]
  5428.  
  5429.      DESCRIPTION
  5430.  
  5431.       Enters Icom's internal Text Editor, or the external editor defined by
  5432.       the user (main setup/Filenames and Paths screen, main setup variable
  5433.       *editor).  sFILENAME is an optional [D:][\PATH\]FILENAME[.EXT] to load
  5434.       (a filename with optional drive, path and extension) to load.  nLINENUM
  5435.       is only valid when *editor is blank (no external editor), and it
  5436.       specifies an optional line number to position the cursor to after
  5437.       loading sFILENAME.
  5438.  
  5439.       NOTE: If you want to ensure use of Icom's internal Text Editor, simply
  5440.       save the *editor main setup variable, clear it, then call EDIT. 
  5441.       Example:
  5442.  
  5443.       variable filename $SCRIPT_DIR "SCRDEMO.SCR"
  5444.       variable oldeditor *editor  ;save external editor (if any)
  5445.  
  5446.       assign *editor ""           ;clear external editor
  5447.       EDIT filename 100           ;edit C:\ICOM\SCR\SCRDEMO.SCR, position to
  5448.                                   ; line 100
  5449.       assign *editor oldeditor    ;restore original external editor
  5450.  
  5451.       This should only be done when you must seek to a specific line number in
  5452.       a file.  You should otherwise let the user edit files in his preferred
  5453.       external text editor.
  5454.  
  5455.      SEE ALSO
  5456.  
  5457.       LIST
  5458.  
  5459.      EXAMPLE
  5460.  
  5461.  
  5462.  
  5463.  
  5464.      Intellicomm v2.01               SCRIPT.DOC                             83
  5465.      
  5466.      
  5467.  
  5468.       variable filename $HOME_DIR "POSTMAIL.BAT"
  5469.       
  5470.       pause "Press a key to edit POSTMAIL.BAT..."
  5471.       edit filename
  5472.  
  5473.      ERASELINE________________________________________________________________
  5474.  
  5475.      SUMMARY
  5476.  
  5477.       ERASELINE nLINE [nCOLOR]
  5478.  
  5479.      DESCRIPTION
  5480.  
  5481.       Clears screen line nLINE changing the line to nCOLOR.  If nCOLOR is
  5482.       omitted $SCRN_COLOR is assumed.  nLINE can be any number from 1 (top
  5483.       line) to $SCRN_HEIGHT (the bottom screen line).  On EGA/VGA displays,
  5484.       $SCRN_HEIGHT can be 25, 42, or 50.  On other displays the screen height
  5485.       is limited to 25 lines.  Note that the status line is normally on the
  5486.       last line of the screen ($SCRN_HEIGHT) and CAN be overwritten by
  5487.       ERASELINE if desired.
  5488.  
  5489.       ERASELINE does not move the screen cursor.  Use 'GOTOXY 1 nLINE' (where
  5490.       nLINE is the line specified in ERASELINE) if you wish to move the cursor
  5491.       to the beginning of the blank line.
  5492.  
  5493.      SEE ALSO
  5494.  
  5495.       CLS, SCROLL, VPUSH, VPOP, $SCRN_COLOR, $SCRN_HEIGHT
  5496.  
  5497.      EXAMPLE
  5498.  
  5499.       ERASELINE 1 $TERM_COLOR   ;clear first line on screen to $TERM_COLOR
  5500.       printraw -1 1 $TERM_COLOR "Centered Title on line 1"  ;-1 centers line
  5501.  
  5502.       ERASELINE 2               ;clear line 2 to the current screen color
  5503.  
  5504.      EXEC_____________________________________________________________________
  5505.  
  5506.      SUMMARY
  5507.  
  5508.       EXEC [SW:|NS:][D:\PATH\]FNAME[.EXT] [PARM ...] [>redirect | >>redirect]
  5509.  
  5510.       (Sorry!  It looks terribly complicated, but it isn't as bad as you
  5511.       think.)
  5512.  
  5513.      DESCRIPTION
  5514.  
  5515.       EXEC executes file FNAME, passing any specified parameters to it, then
  5516.       returns to the script (continuing at the next script line, if any). 
  5517.       FNAME is the external program to execute, and can include a D:\PATH\ (or
  5518.       just a \PATH\) if the program to execute is not on the DOS PATH.  You
  5519.       may include an extension as well, but it must be either .COM or .EXE. 
  5520.       .BAT files are not supported by EXEC (use the DOS command to execute DOS
  5521.       commands such as 'DIR', etc., or batch files).  You may precede FNAME
  5522.  
  5523.  
  5524.  
  5525.  
  5526.      Intellicomm v2.01               SCRIPT.DOC                             84
  5527.      
  5528.      
  5529.  
  5530.       with SW: (Swap) to force Icom to swap itself out of memory (to XMS/EMS
  5531.       if available, or to disk if not) leaving the external program with lots
  5532.       of free memory to work with.  Or you can precede FNAME with NS: (No
  5533.       Swap) to force Icom to stay in memory.  The advantage of the former is
  5534.       that you can run very large external programs, since Icom will free up
  5535.       all the memory it was using, minus just about 200 bytes of code (which
  5536.       it uses to swap itself back in after the program finishes).  The
  5537.       advantage of the latter is that it's faster, since no swapping takes
  5538.       place.  You can try NS: to avoid a swap first if you like.  If you get a
  5539.       "Not enough memory" error trying to run the external program, precede
  5540.       the command with SW: to force a swap.
  5541.  
  5542.       If the executed program displays output to STDOUT (DOS standard output
  5543.       device, as opposed to direct screen writes which most non-command line
  5544.       utilities use), you can have the output redirected to a file or other
  5545.       device such as PRN in the usual manner by following the command with
  5546.       either one or two 'greater than' (>) signs, followed by the name of the
  5547.       file or device you want to redirect TO.  Examples:
  5548.  
  5549.         EXEC "UTIL.EXE /parm1 /parm2 > OUTPUT.FIL"
  5550.         EXEC "C:\UTIL\UTIL2.COM *.* /parm1 >>\TEMP\OUTPUT.FIL"
  5551.  
  5552.       The first example redirects output from UTIL.EXE into a file (in the
  5553.       current directory; whatever it happened to be) called OUTPUT.FIL.  You
  5554.       could then LIST "OUTPUT.FIL" and view the results, etc.  Since only one
  5555.       '>' was specified, if OUTPUT.FIL existed in the current directory, it
  5556.       would be overwritten with the new output.
  5557.  
  5558.       The second example redirects output from C:\UTIL\UTIL2.COM into a file
  5559.       called \TEMP\OUTPUT.FIL.  Since two '>>' greater thans were specified,
  5560.       output would be appended (added to the end of) \TEMP\OUTPUT.FIL if it
  5561.       already existed.
  5562.  
  5563.       If you specify a device name to redirect to, do NOT follow the device
  5564.       name with a colon.  For example use '> PRN' and not '> PRN:'.  Note that
  5565.       these are the only two forms of redirection the EXEC command supports. 
  5566.       It does not support pipes (|) or input redirection (<).  You must use
  5567.       the DOS command for those.
  5568.  
  5569.       When to use EXEC vs. using the DOS command?  EXEC is designed to run
  5570.       only .COM or .EXE programs and it does NOT invoke a copy of the command
  5571.       processor (COMMAND.COM usually) to execute the specified program.  This
  5572.       is an important point when you must check the error return code from a
  5573.       program such as a virus checker or the like, since COMMAND.COM (which is
  5574.       what the 'DOS' command uses to run external programs/commands) does
  5575.       *not* return the errorlevel of the program it executes.  The advantage
  5576.       of the 'DOS' command is that you can run .BAT files, and can execute
  5577.       internal DOS commands such as COPY, DEL, MKDIR, RMDIR (though using the
  5578.       script equivalents of these commands is faster).  The disadvantage of
  5579.       using the DOS command is that you cannot check the error return code (if
  5580.       any) of the program you execute.  With the EXEC command, you *can* check
  5581.       the error code returned by the program (see below) but you cannot
  5582.       execute .BAT files or internal DOS commands which require COMMAND.COM.
  5583.  
  5584.  
  5585.  
  5586.  
  5587.      Intellicomm v2.01               SCRIPT.DOC                             85
  5588.      
  5589.      
  5590.  
  5591.      ERRORLEVEL
  5592.  
  5593.       If the program is successfully executed, $ERRORLEVEL is set to the
  5594.       return code of the program (or to a negative value if the program could
  5595.       not be executed).  This is similar to the 'ERRORLEVEL' variable you can
  5596.       test from a batch (.BAT) file after executing a program.
  5597.  
  5598.        1+   Any value above zero is the return code of the program that was
  5599.             executed.  Such a value will only be useful if the program's
  5600.             documentation specifically outlines the MEANING of error return
  5601.             codes.  Some programs do not return a value, and in those cases
  5602.             it's useless to test for an $ERRORLEVEL above zero.
  5603.        0    Program successfully loaded and executed.  Again, unless a
  5604.             program's documentation specifically states that it sets the DOS
  5605.             errorlevel to zero on successful execution, you should not assume
  5606.             that you'll get a zero return code on successful execution.  Some
  5607.             programs just leave errorlevel alone ... in which case it could be
  5608.             set to any (zero or positive) value when the program finishes. 
  5609.             You're free to always check for a NEGATIVE $ERRORLEVEL after an
  5610.             EXEC (see below), but only check for zero or greater if you know
  5611.             the program you just EXECed returns an errorlevel.
  5612.       -1    No such file or directory (program not found; remember to specify
  5613.             the full D:\PATH\ to the file if it isn't in a directory on your
  5614.             DOS PATH).  Programs never return this errorlevel.  It is set by
  5615.             the EXEC command.
  5616.       -2    Too many open files (no file handles).  Increase the FILES= in
  5617.             your CONFIG.SYS file, then reboot to remedy the situation. 
  5618.             Programs never return this errorlevel.  It is set by the EXEC
  5619.             command.
  5620.       -3    Not enough memory to execute the program.  You can remedy this one
  5621.             by preceding the command with "SW:" to have Icom swap itself out
  5622.             of memory before executing the external program.  Programs never
  5623.             return this errorlevel.  It is set by the EXEC command.
  5624.  
  5625.      SEE ALSO
  5626.  
  5627.       DOS
  5628.  
  5629.      EXAMPLE
  5630.  
  5631.       EXEC "SW:C:\UTIL\BIGPROG.EXE /1stparm /2ndparm"
  5632.  
  5633.       if $ERRORLEVEL < 0      ;less than zero?
  5634.        print "Unable to execute BIGPROG.EXE, errorcode: " $ERRORLEVEL
  5635.       else
  5636.        print "BIGPROG.EXE returned errorlevel: " $ERRORLEVEL 
  5637.       endif
  5638.  
  5639.      EXIST____________________________________________________________________
  5640.  
  5641.      SUMMARY
  5642.  
  5643.       EXIST sFILESPEC cCOMMAND
  5644.  
  5645.  
  5646.  
  5647.  
  5648.      Intellicomm v2.01               SCRIPT.DOC                             86
  5649.      
  5650.      
  5651.  
  5652.      DESCRIPTION
  5653.  
  5654.       If sFILESPEC exists, cCOMMAND is executed.  If sFILESPEC doesn't exist,
  5655.       cCOMMAND is skipped.
  5656.  
  5657.       sFILESPEC is a file specification (wildcards * and ? are accepted)
  5658.       including an optional drive and path (D:\PATH\*.BAT for example).  If
  5659.       you omit the drive (D:) the current drive ($CURDRIVE) is assumed.  If
  5660.       both the drive and path are omitted, the current path is assumed
  5661.       ($CURDIR).
  5662.  
  5663.      ERRORLEVEL
  5664.  
  5665.       No errorlevel is necessary.  Use cCOMMAND.
  5666.  
  5667.      SEE ALSO
  5668.  
  5669.       DISKFIND, FINDFIRST, FINDNEXT, NOTEXIST
  5670.  
  5671.      EXAMPLE
  5672.  
  5673.       variable filename $HOME_DIR "POSTDOWN.BAT"
  5674.       exist filename edit filename  ;edit POSTDOWN.BAT if it exists
  5675.  
  5676.      EXIT_____________________________________________________________________
  5677.  
  5678.      SUMMARY
  5679.  
  5680.       EXIT [nERRORCODE]
  5681.  
  5682.      DESCRIPTION
  5683.  
  5684.       Exits the script processor.  Use EXIT if you have chained to another
  5685.       script (using the SCRIPT command) and you don't wish to return to the
  5686.       original script.
  5687.  
  5688.       nERRORCODE is only valid if Intellicomm is in fully automated mode (i.e.
  5689.       the script must have been called via a job Custom Command/Run Script
  5690.       task).  If nERRORCODE is 0 (zero) no action is taken by Intellicomm.  If
  5691.       nERRORCODE is 1 or greater, Intellicomm cancels the rest of the job
  5692.       tasks for the CURRENT BBS, and removes the current BBS from the dialing
  5693.       queue.  If nERRORCODE is less than zero (-1, -2, etc) Intellicomm aborts
  5694.       all automated jobs.
  5695.  
  5696.       NOTE: If a non-zero nERRORCODE follows the EXIT command, Intellicomm
  5697.       prints a message to the screen stating "Script aborted by EXIT code:
  5698.       nERRORCODE".
  5699.  
  5700.      SEE ALSO
  5701.  
  5702.       SCRIPT, RETURN, SCRTUTOR.DOC section "WHAT HAPPENS WHEN A SCRIPT ENDS?"
  5703.  
  5704.      EXAMPLE
  5705.  
  5706.  
  5707.  
  5708.  
  5709.      Intellicomm v2.01               SCRIPT.DOC                             87
  5710.      
  5711.      
  5712.  
  5713.       waitfor "Some text" 120 major_error
  5714.       ...
  5715.       return
  5716.  
  5717.      major_error:
  5718.       EXIT 1      ;abort all scripts, and the automated job for current BBS as
  5719.                   ; well
  5720.  
  5721.      FCLOSE___________________________________________________________________
  5722.  
  5723.      SUMMARY
  5724.  
  5725.       FCLOSE vHANDLE
  5726.  
  5727.      DESCRIPTION
  5728.  
  5729.       Closes the file vHANDLE.  vHANDLE must be a valid file handle stored by
  5730.       the FOPEN command.
  5731.  
  5732.      ERRORLEVEL
  5733.  
  5734.       0  FCLOSE successful
  5735.       1  FCLOSE unsuccessful (disk error; most likely the disk is full).
  5736.  
  5737.      SEE ALSO
  5738.  
  5739.       FOPEN
  5740.  
  5741.      EXAMPLE
  5742.  
  5743.      FFLUSH___________________________________________________________________
  5744.  
  5745.      SUMMARY
  5746.  
  5747.       FFLUSH vHANDLE
  5748.  
  5749.      DESCRIPTION
  5750.  
  5751.       Immediately writes any data in vHANDLE's file output buffer to disk.
  5752.       vHANDLE is the variable you used when you FOPENed the file.
  5753.  
  5754.       FPUTS and FPUTC do not write data to disk immediately.  They buffer data
  5755.       until an effecient disk write can be made (or until FCLOSE is called). 
  5756.       If you have something very important to write to disk, use FFLUSH after
  5757.       FPUTS / FPUTC, etc., to immediately write the data to disk.  If the
  5758.       computer locks up, or the power goes out while data is waiting to be
  5759.       written to disk in the file output buffer, the data will be lost.
  5760.  
  5761.       NOTE 1: FFLUSH is automatically called when you FCLOSE a file.
  5762.  
  5763.       NOTE 2: Disk cache programs (such as DOS's SMARTDrive) also buffer data
  5764.       in memory, for more effecient disk writes.  FFLUSH cannot force a disk
  5765.       cache to write data to disk, so if a disk cache with a write-behind
  5766.       buffer is operating, FFLUSH has no effect.  This is not a limitation of
  5767.  
  5768.  
  5769.  
  5770.  
  5771.      Intellicomm v2.01               SCRIPT.DOC                             88
  5772.      
  5773.      
  5774.  
  5775.       Icom's script language, or even a limitation of DOS: it's a limitation
  5776.       of using disk cache write-behind buffers.  They write data on their own
  5777.       time, and I have yet to figure out how to force any disk cache to write
  5778.       its data to disk, if indeed there is any way (aside from executing non-
  5779.       standard and slow commands at the DOS prompt).  If anyone knows the
  5780.       secret, feel free to pass it along, as I'd like to have FFLUSH force
  5781.       disk cache programs to write to disk as well.
  5782.  
  5783.      ERRORLEVEL
  5784.  
  5785.       0  Disk write (FLUSH) was successful.
  5786.       1  Disk write unsuccessful (the disk is likely full).
  5787.  
  5788.      SEE ALSO
  5789.  
  5790.       FOPEN, FCLOSE
  5791.  
  5792.      EXAMPLE
  5793.  
  5794.      FGETC____________________________________________________________________
  5795.  
  5796.      SUMMARY
  5797.  
  5798.       FGETC vBUFFER vHANDLE
  5799.  
  5800.      DESCRIPTION
  5801.  
  5802.       Gets a single character from file vHANDLE (a valid file handle variable
  5803.       as stored by FOPEN) and stores the character in variable vBUFFER.  Also
  5804.       increments the file pointer by one character (multiple calls to FGETC go
  5805.       through a file character by character).
  5806.  
  5807.      ERRORLEVEL
  5808.  
  5809.       0  FGETC successful (a character was stored in vBUFFER).
  5810.       1  End of file (vBUFFER contains -1).
  5811.  
  5812.      SEE ALSO
  5813.  
  5814.       FGETS
  5815.  
  5816.      EXAMPLE
  5817.  
  5818.       variable fh
  5819.       variable buf
  5820.  
  5821.       fopen fh "TEST.DAT" "r"   ;open TEST.DAT for reading
  5822.       while 1                   ;loop until BREAK
  5823.        FGETC buf fh
  5824.        if $errorlevel = 1 break ;end of file
  5825.        printnc buf
  5826.       endwhile
  5827.       fclose fh
  5828.  
  5829.  
  5830.  
  5831.  
  5832.      Intellicomm v2.01               SCRIPT.DOC                             89
  5833.      
  5834.      
  5835.  
  5836.      FGETS____________________________________________________________________
  5837.  
  5838.      SUMMARY
  5839.  
  5840.       FGETS vBUFFER vHANDLE
  5841.  
  5842.      DESCRIPTION
  5843.  
  5844.       Gets a line of characters from file vHANDLE (a valid file handle
  5845.       variable as stored by FOPEN) and stores the characters in variable
  5846.       vBUFFER.  Also increments the file pointer by the number of characters
  5847.       read (multiple calls to FGETS go through a file line by line).
  5848.  
  5849.       FGETS stops reading when a line feed character is encountered, 256
  5850.       characters (the maximum number of characters that can be stored in a
  5851.       script variable) have been read, or the end of the file is encountered. 
  5852.       In text files, carriage return / line feed pairs end each line.  FPUTS
  5853.       also writes a carriage return / line feed after the line of data
  5854.       written.
  5855.  
  5856.       NOTE: The carriage return / line feed pair at the end of each line are
  5857.       stripped by FGETS, since you will rarely want them.
  5858.  
  5859.      ERRORLEVEL
  5860.  
  5861.       0  FGETS successful (characters were stored in vBUFFER).
  5862.       1  End of file (vBUFFER is empty).  It's possible for vBUFFER to be
  5863.          empty after FGETS, but to not have an end of file condition
  5864.          ($ERRORLEVEL 1).  Blank lines in text files will result in an empty
  5865.          vBUFFER, but $ERRORLEVEL will *not* be set to 1 until the end of the
  5866.          file is reached.
  5867.  
  5868.      SEE ALSO
  5869.  
  5870.       FGETC
  5871.  
  5872.      EXAMPLE
  5873.  
  5874.       variable fh
  5875.       variable buf
  5876.  
  5877.       fopen fh "TEST.DAT" "r"   ;open TEST.DAT for reading
  5878.       while 1                   ;loop until BREAK
  5879.        FGETS buf fh
  5880.        if $errorlevel = 1 break ;end of file
  5881.        printnc buf
  5882.       endwhile
  5883.       fclose fh
  5884.  
  5885.      FILEMAN__________________________________________________________________
  5886.  
  5887.      SUMMARY
  5888.  
  5889.       FILEMAN [sDRIVEDIR] [sFILESPEC]
  5890.  
  5891.  
  5892.  
  5893.  
  5894.      Intellicomm v2.01               SCRIPT.DOC                             90
  5895.      
  5896.      
  5897.  
  5898.      DESCRIPTION
  5899.  
  5900.  
  5901.       Enters Icom's internal File Manager (same as pressing [Alt-F] from most
  5902.       places in Intellicomm).  sDRIVEDIR is an optional drive and directory
  5903.       (D:\PATH) to display.  If omitted, $CUR_DIR is assumed.  sFILESPEC is an
  5904.       optional filespec to display (wildcards ? and * are accepted).  If
  5905.       omitted, *.* is assumed.
  5906.  
  5907.      EXAMPLE
  5908.  
  5909.       FILEMAN $HOME_DIR "*.*"  ;display all files in the \ICOM directory
  5910.  
  5911.      FILESIZE_________________________________________________________________
  5912.  
  5913.      SUMMARY
  5914.  
  5915.       FILESIZE vBUFFER [sFILENAME]
  5916.  
  5917.      DESCRIPTION
  5918.  
  5919.       Stores the size (in bytes) of file sFILENAME in variable vBUFFER.  If
  5920.       sFILESPEC is omitted, the last file found with EXIST, FINDFIRST, or
  5921.       FINDNEXT is assumed.  sFILENAME can be a full D:\PATH\FILENAME.EXT
  5922.       (drive, path, filename, extension).  If you omit either the drive or the
  5923.       path, the current drive/directory is assumed.
  5924.  
  5925.      ERRORLEVEL
  5926.  
  5927.       There's no need to check $ERRORLEVEL after FILESIZE.  If the file
  5928.       doesn't exist, vBUFFER will contain -1 (minus one).
  5929.  
  5930.      SEE ALSO
  5931.  
  5932.       FINDFIRST, FINDNEXT, $FSIZE
  5933.  
  5934.      FINDFIRST________________________________________________________________
  5935.  
  5936.      SUMMARY
  5937.  
  5938.       FINDFIRST vBUFFER sFILESPEC [nATTRIBUTES]
  5939.  
  5940.      DESCRIPTION
  5941.  
  5942.       FINDFIRST is used to check for the existence of files (including hidden
  5943.       files and system files), directories, and/or disk labels.
  5944.  
  5945.       vBUFFER is a variable where FINDFIRST will store the name of the first
  5946.       matching file or directory name.
  5947.  
  5948.       sFILESPEC is the file specification to search for (wildcards ? and * are
  5949.       accepted), and it may contain an optional drive and path (D:\PATH). 
  5950.       Examples: "C:\ICOM\*.*", "\ICOM\SCR\POST????.SCR", etc).  If the drive
  5951.       is omitted, the current drive is assumed ($CUR_DRIVE).  If the path is
  5952.  
  5953.  
  5954.  
  5955.  
  5956.      Intellicomm v2.01               SCRIPT.DOC                             91
  5957.      
  5958.      
  5959.  
  5960.       omitted the current directory is assumed.  The filename portion MUST be
  5961.       specified.  *.* is not assumed if you specify a D:\PATH but omit a
  5962.       filespec.
  5963.       nATTRIBUTES allows you to specify file attributes that the file much
  5964.       match in order to be found by FINDFIRST.  If nATTRIBUTES is omitted, 0
  5965.       (normal and read only files) is assumed.  To specify nATTRIBUTES, select
  5966.       one or more attributes from the list below:
  5967.  
  5968.        0   Normal and read only files
  5969.        2   Hidden files
  5970.        4   System files
  5971.        8   Disk volume label
  5972.        16  Subdirectories
  5973.  
  5974.       ...and ADD the numbers up.  For example, to find normal files, hidden
  5975.       files, and subdirectories, add 0 (not necessary really; 0 is useless
  5976.       when adding), 2 (Hidden files) and 16 (Subdirectories) together (0 + 2 +
  5977.       16 = 18) and specify 18 as the nATTRIBUTES parameter.
  5978.  
  5979.       NOTE: If FINDFIRST locates a file, directory or volume label, it stores
  5980.       the FILENAME.EXT in vBUFFER, and also sets the $FXXXX variables listed
  5981.       in the "SEE ALSO" section below.  The $FXXXX variables allow you to
  5982.       check the date, time, and attributes of the item that FINDFIRST located.
  5983.  
  5984.      ERRORLEVEL
  5985.  
  5986.       0  FINDFIRST successful (a matching item was found and its name has been
  5987.          stored in vBUFFER).
  5988.       1  FINDFIRST unsuccessful (nothing found matching sFILESPEC with the
  5989.          specified nATTRIBUTES).
  5990.  
  5991.      SEE ALSO
  5992.  
  5993.       EXIST, FINDNEXT, NOTEXIST, $FARCH, $FDATE, $FDAY, $FHIDDEN, $FHOUR,
  5994.       $FMIN, $FMONTH, $FRDONLY, $FSEC, $FSIZE, $FSUBDIR, $FSYSTEM, $FTIME,
  5995.       $FVOLID, $FYEAR
  5996.  
  5997.      EXAMPLE
  5998.  
  5999.        ;simulates a regular 'DIR' command from DOS, but shows Hidden and
  6000.        ; System files/subdirectories as well
  6001.  
  6002.       variable buf
  6003.  
  6004.       FINDFIRST buf "C:\*.*" 8   ;get the disk volume label (always in root
  6005.                                  ; directory)
  6006.       print "The volume in drive C: is " buf
  6007.       print
  6008.  
  6009.       FINDFIRST buf "C:\*.*" 22  ;all attributes except volume label
  6010.  
  6011.       while $ERRORLEVEL = 0      ;end loop when no more files
  6012.        strpad buf " " 15         ;pad with spaces to a length of 15
  6013.        printnc buf
  6014.  
  6015.  
  6016.  
  6017.  
  6018.      Intellicomm v2.01               SCRIPT.DOC                             92
  6019.      
  6020.      
  6021.  
  6022.        if $FSUBDIR = "+"         ;is it a subdirectory?
  6023.         printnc "<DIR>          "
  6024.        else
  6025.         assign buf $FSIZE        ;get the filesize
  6026.         strpadl buf " " 15       ;pad left side with spaces to 15 chars
  6027.         printnc buf
  6028.        endif
  6029.        printnc "  " $FDATE
  6030.        print "  " $FTIME
  6031.        findnext buf              ;also sets $ERRORLEVEL = 1 if no more files
  6032.       endwhile
  6033.  
  6034.      FINDNEXT_________________________________________________________________
  6035.  
  6036.      SUMMARY
  6037.  
  6038.       FINDNEXT vBUFFER
  6039.  
  6040.      DESCRIPTION
  6041.  
  6042.       Finds the next matching file after using FINDFIRST, and (if any more
  6043.       files exist) stores the name of the item in variable vBUFFER.  FINDNEXT
  6044.       is only of use when wildcards (* or ?) were used in the original
  6045.       FINDFIRST 'sFILESPEC' parameter.  For example, this is useless:
  6046.  
  6047.        findfirst buf "c:\icom\icom.exe"
  6048.        FINDNEXT buf    ;can't possible have another file called ICOM.EXE
  6049.  
  6050.       This isn't:
  6051.  
  6052.        findfirst buf "c:\icom\icom.*"   ;any extension will do, so you could
  6053.                                         ; match ICOM.EXE, ICOM.PWD, ICOM.HLP,
  6054.                                         ; ICOM.DAT, etc.
  6055.        FINDNEXT buf                     ;this is likely to find another file
  6056.                                         ; matching ICOM.*
  6057.  
  6058.       NOTE 1: The attributes (nATTRIBUTES) parameter specified in the original
  6059.       FINDFIRST also apply to FINDNEXT.  So if you were searching for
  6060.       Subdirectories in the original FINDFIRST, FINDNEXT would only find
  6061.       Subdirectories.
  6062.  
  6063.       NOTE 2: The $FXXXX variables listed in the 'SEE ALSO' section of
  6064.       FINDFIRST are also set by FINDNEXT.  See FINDFIRST for details.
  6065.  
  6066.      ERRORLEVEL
  6067.  
  6068.       0  FINDNEXT successful (the name of the item was stored in vBUFFER).
  6069.       1  FINDNEXT unsuccessful (nothing else was found).
  6070.  
  6071.      SEE ALSO
  6072.  
  6073.       FINDFIRST
  6074.  
  6075.      EXAMPLE
  6076.  
  6077.  
  6078.  
  6079.  
  6080.      Intellicomm v2.01               SCRIPT.DOC                             93
  6081.      
  6082.      
  6083.  
  6084.        ;display all .BAT files in the \ICOM directory
  6085.  
  6086.       variable buf
  6087.  
  6088.       findfirst buf "\ICOM\*.BAT"
  6089.       while $ERRORLEVEL = 0
  6090.        print buf
  6091.        FINDNEXT buf
  6092.       endwhile
  6093.  
  6094.      FNSTRIP__________________________________________________________________
  6095.  
  6096.      SUMMARY
  6097.  
  6098.       FNSTRIP vBUFFER sFILESPEC nMODE
  6099.  
  6100.      DESCRIPTION
  6101.  
  6102.       Gets portions of sFILESPEC according to nMODE and stores the result in
  6103.       vBUFFER.
  6104.  
  6105.       Values for nMODE:
  6106.  
  6107.       0  Full filename
  6108.       1  All except the drive
  6109.       2  D:NAME.EXT      Drive, name, extension
  6110.       3  NAME.EXT        Name and extension
  6111.       4  D:\PATH\NAME    Drive, path, and name (no extension)
  6112.       5  \PATH\NAME      Path and name (no extension)
  6113.       6  D:NAME          Drive and name (no extension)
  6114.       7  NAME            Name only (no extension)
  6115.       12 D:\PATH\        Drive and path only
  6116.       13 \PATH\          Path only
  6117.       14 D:              Drive only
  6118.       15 .EXT            Extension only
  6119.  
  6120.      EXAMPLE
  6121.  
  6122.       variable drive_path
  6123.  
  6124.       FNSTRIP drive_path "D:\PATH\FILENAME.EXT" 12
  6125.       print drive_path   ;this prints D:\PATH\
  6126.  
  6127.      FOPEN____________________________________________________________________
  6128.  
  6129.      SUMMARY
  6130.  
  6131.       FOPEN vHANDLEBUF sFILENAME sMODE
  6132.  
  6133.      DESCRIPTION
  6134.  
  6135.       NOTE: Before using FOPEN, please read the section "PERMANENT VARIABLES:
  6136.       INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC.
  6137.  
  6138.  
  6139.  
  6140.  
  6141.      Intellicomm v2.01               SCRIPT.DOC                             94
  6142.      
  6143.      
  6144.  
  6145.       Opens file sFILENAME for reading/writing or both (as specified by sMODE)
  6146.       and stores a file 'handle' in variable vHANDLEBUF.
  6147.  
  6148.       vHANDLEBUF should be a variable defined with the script VARIABLE
  6149.       command.  vHANDLEBUF is used to distinguish one open file from another (
  6150.       must then be used by various other file-related commands, to manipulate
  6151.       the open file.
  6152.  
  6153.       sFILENAME is the name of the file to open.  A drive and path can (and
  6154.       should) be specified along with the filename.  Wildcards (? and *) are
  6155.       NOT accepted by FOPEN.
  6156.  
  6157.       sMODE must be one of the following values:
  6158.  
  6159.       "r"   Opens sFILENAME for Reading (no writes are allowed: the file
  6160.             cannot be modified).
  6161.       "w"   Opens sFILENAME for Writing.  If the file exists, its contents
  6162.             will be destroyed.  No reads are allowed in this mode.
  6163.       "a"   Opens sFILENAME for Appending (no reads are allowed; data is added
  6164.             to the end of the file).  If the file does not exist, it will be
  6165.             created.
  6166.       
  6167.       Advanced (open for reading AND writing):
  6168.  
  6169.       "r+"  Opens sFILENAME for Reading and writing.  If sFILENAME does not
  6170.             exist, it will be created.
  6171.       "w+"  Opens sFILENAME for Writing and reading.  If sFILENAME exists, its
  6172.             contents are destroyed (use "r+" to open for read/write without
  6173.             destroying existing files).
  6174.       "a+"  Opens sFILENAME for reading and Appending (adds to the end).  If
  6175.             the file doesn't exist, it will be created.
  6176.  
  6177.       NOTE 1: Never open the same file twice.  For example, you can open the
  6178.       capture file to add some data to it, but you must first call CAPCLOSE to
  6179.       close the file:
  6180.  
  6181.        variable f
  6182.  
  6183.        cappush     ;save capture status/filename
  6184.        capclose
  6185.        FOPEN f $CAP_NAME "a"
  6186.        fputs f "^M^JAdd something to the capture file...^M^J"
  6187.        fclose f
  6188.        cappop      ;reset the capture file to its original state
  6189.  
  6190.       You 'can' get away with opening the same file multiple times on some
  6191.       computers, but if SHARE is loaded the user will receive an error message
  6192.       and the FOPEN will not succeed.  Exception 12 and 13 errors (which
  6193.       effectively hang the machine, requiring a re-boot) can also result from
  6194.       operating on an open file.
  6195.  
  6196.       NOTE 2: Never attempt to DELETE or RENAME an open file.  It will result
  6197.       in lost chains, and even exception 13's.
  6198.  
  6199.  
  6200.  
  6201.  
  6202.      Intellicomm v2.01               SCRIPT.DOC                             95
  6203.      
  6204.      
  6205.  
  6206.       NOTE 3: Most of the file-oriented commands such as COPY, APPEND, etc.,
  6207.       perform their own FOPEN.  Don't attempt to use a file-oriented command
  6208.       on an open file (FINDFIRST/FINDNEXT/EXIST/NOTEXIT are fine, but most
  6209.       others can cause SHARE or exception errors if used on an open file).
  6210.  
  6211.       NOTE 4: Most Intellicomm data files (.BAT, .BIF, .INI, .KWD, .SCR [even
  6212.       the currently executing script]) are CLOSED when scripts are running. 
  6213.       Exceptions are the capture file ($CAP_NAME, which can be closed with
  6214.       CAPCLOSE), any files you've previously opened with FOPEN (which can be
  6215.       closed with FCLOSE), and any catalogs you've opened with COPEN (which
  6216.       opens *5* files: the .DBF, .DBT, and the 3 .NDX files related to the
  6217.       catalog.  Catalogs can be closed with CCLOSE).  You can safely FOPEN any
  6218.       other Intellicomm data files, if you know what you're doing and have a
  6219.       specific need to use a data file directly.  When Intellicomm needs
  6220.       information from a data file it normally opens the file, takes what it
  6221.       needs, and closes it immediately.  This is true even while scripts are
  6222.       running: LOADBIF, for example, does not leave the .BIF open.  It simply
  6223.       loads the information into memory, and the .BIF file itself is closed
  6224.       when LOADBIF finishes.
  6225.  
  6226.       NOTE 5: Never write to ICOM.USE (the Usage Log) unless you've read the
  6227.       Call Data Standard specifications (available on many BBS's as CDS.ZIP). 
  6228.       Icom's Usage Log follows a fixed format, and writing anything other than
  6229.       comments to the file (which should be done with the STAMP command and
  6230.       not with FOPEN/FPUTS/FCLOSE) could render the entire Usage Log
  6231.       unreadable.
  6232.  
  6233.      ERRORLEVEL
  6234.  
  6235.       0  sFILENAME successfully opened.
  6236.       1  sFILENAME doesn't exist (read mode) or couldn't be created (invalid
  6237.          drive, path or filename in write mode, or root directory full).
  6238.       2  Too many open files.  Tell the user to increase the FILES= line in
  6239.          the computer's CONFIG.SYS file.
  6240.       3  Not enough memory to open the file.
  6241.       4  Permission denied (tried to open a read-only file in Write mode).
  6242.       5  Miscellaneous errors too numerous and obscure to mention.  The file
  6243.          wasn't opened.
  6244.  
  6245.       NOTE: If you get anything other than $ERRORLEVEL = 0 after FOPEN, do not
  6246.       attempt to use vHANDLEBUF.  This bit below would abort with an "Invalid
  6247.       file handle" error:
  6248.  
  6249.       variable f
  6250.  
  6251.       FOPEN f "|INVALID" "w"   ; '|' is not valid in DOS filenames
  6252.       if $ERRORLEVEL > 0
  6253.        fclose f                ;aborts the script.  The file is NEVER opened
  6254.       endif                    ; if an $errorlevel is returned, and the value
  6255.                                ; stored in variable 'f' will be 0 (zero) which
  6256.                                ; is always an invalid file handle.
  6257.  
  6258.  
  6259.      SEE ALSO
  6260.  
  6261.  
  6262.  
  6263.  
  6264.      Intellicomm v2.01               SCRIPT.DOC                             96
  6265.      
  6266.      
  6267.  
  6268.       APPEND, APPENDS, APPENDSNC (quicker ways to add to a file without
  6269.       bothering with FOPEN/FCLOSE), FCLOSE
  6270.  
  6271.      EXAMPLE 1
  6272.  
  6273.       variable datfile
  6274.       FOPEN datfile "TEMP.$$$" "w"
  6275.       fputs datfile "Store this on line 1 of TEMP.$$$"
  6276.       fputs datfile "Store this on line 2 of TEMP.$$$"
  6277.       fclose datfile
  6278.  
  6279.      EXAMPLE 2
  6280.  
  6281.       variable key
  6282.       variable f
  6283.  
  6284.       msgopen "Please turn on your printer and press a key..."
  6285.       inkey key
  6286.       msgclose
  6287.       fopen f $PRN "w"     ;open the printer device for writing
  6288.       fputs f "These lines will be printed on the printer."
  6289.       fputs f "Most printers require a CR before they actually print anything"
  6290.       fputs f "but FPUTS sends a CR so that's no problem.  If you use FPUTC"
  6291.       fputs f "or FPUTSNC (no CR) then your line will not be printed until"
  6292.       fputs f "you send a CR."
  6293.       fputs f "^L"   ;Ctrl-L is a Form Feed.  It causes the printer to move to
  6294.                      ; the top of the next page.
  6295.       fclose f
  6296.  
  6297.      FPUTC____________________________________________________________________
  6298.  
  6299.      SUMMARY
  6300.  
  6301.       FPUTC vHANDLE sCHARACTER
  6302.  
  6303.      DESCRIPTION
  6304.  
  6305.       Writes the character sCHARACTER to the file handle specified by vHANDLE. 
  6306.       vHANDLE must be a file handle obtained via FOPEN.  No carriage return or
  6307.       line feed is added after sCHARACTER (as with FPUTS).
  6308.  
  6309.      ERRORLEVEL
  6310.  
  6311.       0  sCHARACTER was successfully written.
  6312.       1  Unable to write sCHARACTER (the disk is likely full).
  6313.  
  6314.      SEE ALSO
  6315.  
  6316.       FPUTS, FPUTSNC
  6317.  
  6318.      EXAMPLE
  6319.  
  6320.      FPUTS____________________________________________________________________
  6321.  
  6322.  
  6323.  
  6324.  
  6325.      Intellicomm v2.01               SCRIPT.DOC                             97
  6326.      
  6327.      
  6328.  
  6329.      SUMMARY
  6330.  
  6331.       FPUTS vHANDLE sSTRING ...
  6332.  
  6333.      DESCRIPTION
  6334.  
  6335.       Writes sSTRING to the file signified by vHANDLE.  A carriage return and
  6336.       line feed are automatically added to the end of sSTRING (terminating the
  6337.       line in the file).  Use FPUTSNC if you don't want CR/LF added.
  6338.  
  6339.       vHANDLE must be a valid file handle obtained via FOPEN.
  6340.  
  6341.      ERRORLEVEL
  6342.  
  6343.       0  sSTRING was successfully written.
  6344.       1  Unable to write sSTRING (the disk is likely full).
  6345.  
  6346.      SEE ALSO
  6347.  
  6348.       FPUTC, FPUTSNC
  6349.  
  6350.      EXAMPLE
  6351.  
  6352.       variable datfile
  6353.       fopen datfile "TEMP.$$$" "w"
  6354.       FPUTS datfile "Store this on line 1 of TEMP.$$$"
  6355.       FPUTS datfile "Store this on line 2 of TEMP.$$$"
  6356.       fclose datfile
  6357.  
  6358.      FPUTSNC__________________________________________________________________
  6359.  
  6360.      SUMMARY
  6361.  
  6362.       FPUTSNC vHANDLE sSTRING ...
  6363.  
  6364.      DESCRIPTION
  6365.  
  6366.       Writes sSTRING to the file signified by vHANDLE.  A carriage return and
  6367.       line feed are NOT automatically added to the end of sSTRING (as with
  6368.       FPUTS).  Use FPUTS if you want to terminate the line with CR/LF.
  6369.  
  6370.       vHANDLE must be a valid file handle obtained via FOPEN.
  6371.  
  6372.      ERRORLEVEL
  6373.  
  6374.       0  sSTRING was successfully written.
  6375.       1  Unable to write sSTRING (the disk is likely full).
  6376.  
  6377.      SEE ALSO
  6378.  
  6379.       FPUTC, FPUTS
  6380.  
  6381.      EXAMPLE
  6382.  
  6383.  
  6384.  
  6385.  
  6386.      Intellicomm v2.01               SCRIPT.DOC                             98
  6387.      
  6388.      
  6389.  
  6390.       variable datfile
  6391.       fopen datfile "TEMP.$$$" "w"
  6392.       FPUTS datfile "Store this on line 1 of TEMP.$$$"
  6393.       FPUTS datfile "Store this on line 2 of TEMP.$$$"
  6394.       fclose datfile
  6395.  
  6396.      FSEEK____________________________________________________________________
  6397.  
  6398.      SUMMARY
  6399.  
  6400.       FSEEK vHANDLE nOFFSET nORIGIN
  6401.  
  6402.      DESCRIPTION
  6403.  
  6404.       FSEEK is an advanced command that moves the file pointer of the file
  6405.       signified by vHANDLE.  The file pointer determines whether the next
  6406.       read/write will take place, as outlined in "INTRODUCTION TO FILE
  6407.       INPUT/OUTPUT" section of SCRTUTOR.DOC.
  6408.  
  6409.       vHANDLE is a valid file handle obtained by FOPEN.
  6410.  
  6411.       nOFFSET is the number of bytes to seek from nORIGIN (0 = the first byte
  6412.       in the file).  Positive numbers seek forward from nORIGIN, negative
  6413.       numbers seek backwards from nORIGIN.
  6414.  
  6415.       nORIGIN is a number that specifies the initial location of the seek:
  6416.  
  6417.        0 = From the beginning of the file.
  6418.        1 = From the current position of the file pointer.
  6419.        2 = From the end of the file.
  6420.  
  6421.       NOTE: It is legal to seek past the end of a file, but you cannot seek
  6422.       past the beginning of a file.  If you seek past the end of a file, the
  6423.       portion of the file from the original end-of-file to the new FSEEK
  6424.       position will likely contain garbage.  Assume a file called HELLO, with
  6425.       5 bytes in it:
  6426.  
  6427.        HELLO
  6428.  
  6429.       If you did this to modify HELLO in your script:
  6430.  
  6431.        variable f
  6432.        fopen f "HELLO" "r+"   ;open for read/write
  6433.        FSEEK f 10 0           ;seek 10 bytes from the beginning (past the end)
  6434.        fputs f "THERE"
  6435.        fclose f 
  6436.  
  6437.       ...the file HELLO would likely contain garbage between "HELLO" (the
  6438.       original file contents) and "THERE" (the portion added at position 10 in
  6439.       the above example):
  6440.  
  6441.                 1
  6442.       012345678901234   <-- Numeric ruler for reference
  6443.       HELLO%~@-\THERE   <-- Contents of file HELLO after FSEEK 10 0/FPUTS
  6444.  
  6445.  
  6446.  
  6447.  
  6448.      Intellicomm v2.01               SCRIPT.DOC                             99
  6449.      
  6450.      
  6451.  
  6452.      ERRORLEVEL
  6453.  
  6454.       0  FSEEK was successful (the file pointer has been moved).
  6455.  
  6456.       1  FSEEK was unsuccessful (the file pointer remains where it was
  6457.          previously).  This error will occur if you attempt to seek past the
  6458.          beginning of the file ('FSEEK f -100 2' to seek back 100 bytes from
  6459.          the END of the file, on a file that is only 50 bytes long for
  6460.          example).
  6461.  
  6462.      SEE ALSO
  6463.  
  6464.       FOPEN
  6465.  
  6466.      EXAMPLE
  6467.  
  6468.       Please see "PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT / OUTPUT" in
  6469.       SCRTUTOR.DOC for detailed FSEEK explanations and examples.
  6470.  
  6471.       variable fh
  6472.  
  6473.       fopen fh "TEST.$$$" "r+"
  6474.       FSEEK fh 100 0
  6475.       fputs fh "TEST"
  6476.       fclose f
  6477.  
  6478.      FTELL____________________________________________________________________
  6479.  
  6480.      SUMMARY
  6481.  
  6482.       FTELL vBUFFER vHANDLE
  6483.  
  6484.      DESCRIPTION
  6485.  
  6486.       Gets the current position of the file pointer for file vHANDLE and
  6487.       stores it in vBUFFER.
  6488.  
  6489.       vHANDLE must be a valid file handle obtained via FOPEN.
  6490.  
  6491.      EXAMPLE
  6492.  
  6493.       variable fh
  6494.       variable buf
  6495.  
  6496.       fopen fh "TEST.FIL" "r"
  6497.       fgets buf fh
  6498.       FTELL buf fh
  6499.       print "Current positon: " buf
  6500.  
  6501.      GETENV___________________________________________________________________
  6502.  
  6503.      SUMMARY
  6504.  
  6505.       GETENV vBUFFER sENVLABEL
  6506.  
  6507.  
  6508.  
  6509.  
  6510.      Intellicomm v2.01               SCRIPT.DOC                            100
  6511.      
  6512.      
  6513.  
  6514.      DESCRIPTION
  6515.  
  6516.       Gets the contents of envirnment variable sENVLABEL and if found, stores
  6517.       it in vBUFFER.
  6518.  
  6519.      ERRORLEVEL
  6520.  
  6521.       0  Label sENVLABEL was found in the environment and its contents has
  6522.          been stored in vBUFFER.
  6523.       1  Label sENVLABEL does not exist in the environment.
  6524.  
  6525.      SEE ALSO
  6526.  
  6527.       SETENV
  6528.  
  6529.      EXAMPLE
  6530.  
  6531.       variable path
  6532.  
  6533.       GETENV path "PATH"
  6534.       print "PATH=" path
  6535.  
  6536.      GETFNAME_________________________________________________________________
  6537.  
  6538.      SUMMARY
  6539.  
  6540.       GETFNAME [sDIRECTORY] [sFILESPEC] [sHELPLINE]
  6541.  
  6542.      DESCRIPTION
  6543.  
  6544.       This command requires a few skills to use, but it can be very useful in
  6545.       advanced script projects.  GETFNAME accesses a variation of the Icom
  6546.       "File Manager" (FILEMAN command) displaying all files that match
  6547.       sDIRECTORY sFILESPEC (a D:\PATH\FILESPEC the drive, path, AND filespec
  6548.       are all optional) as the File Manager does.  But GETFNAME allows the
  6549.       user to "Select" one or more files for your script to operate on.  Note
  6550.       that D:\PATH\ and FILESPEC are specified *separately* in different
  6551.       parameters.
  6552.  
  6553.       If you omit the 'D:' (Drive) in sDIRECTORY, the current drive is assumed
  6554.       If you omit the \PATH\ portion, the \ICOM directory, or the last
  6555.       directory displayed is assumed (a trailing slash is not necessary when
  6556.       specifying path names, but is acceptable).  If you omit the FILESPEC,
  6557.       *.* is assumed.  Thus if you use:
  6558.  
  6559.        GETFNAME "\"
  6560.  
  6561.       D:\*.* (where D: is the current drive) is displayed to the user.  As in
  6562.       the Icom File Manager, the user can change to a new directory if need
  6563.       be, and can also View, Edit, Find (full disk search), Ren/Move, Delete
  6564.       files, etc., before making a selection.
  6565.  
  6566.       If sHELPLINE is specified, it is displayed in the File Manager message
  6567.       box, until the user presses a key.  Note that if you omit the sFILESPEC
  6568.  
  6569.  
  6570.  
  6571.  
  6572.      Intellicomm v2.01               SCRIPT.DOC                            101
  6573.      
  6574.      
  6575.  
  6576.       parameter but DO want to specify a help line, you must do the following:
  6577.  
  6578.        GETFNAME "\" "" "Help Line"   ;<-- Help must be the THIRD parameter
  6579.  
  6580.       Since the user is able to "Tag" and "Select" multiple files, GETFNAME
  6581.       does not store the selected filename(s) in a script variable, but
  6582.       instead writes all the selected files out to a text file called
  6583.       \ICOM\GETFNAME.LST, which you can read using the script File I/O
  6584.       commands (see the example below).  For example, if you displayed
  6585.       C:\ICOM\*.BAT with GETFNAME, and the user Tagged/Selected the files:
  6586.       POSTMAIL.BAT and POSTDOWN.BAT, the file \ICOM\GETFNAME.LST would contain
  6587.       the following two lines:
  6588.  
  6589.      C:\ICOM\POSTMAIL.BAT
  6590.      C:\ICOM\POSTDOWN.BAT
  6591.  
  6592.      ERRORLEVEL
  6593.  
  6594.       GETFNAME does not set $ERRORLEVEL.  On entry it deletes the file
  6595.       C:\ICOM\GETFNAME.LST if it exists, and thus if the user doesn't select
  6596.       any files, GETFNAME.LST will not exist.  This is how you can determine
  6597.       whether the user selected any files or not: by the existence or non-
  6598.       existence of GETFNAME.LST after GETFNAME finishes (see example below).
  6599.  
  6600.      SEE ALSO
  6601.  
  6602.       DIRFIND, DISKFIND, LOCATEFILE
  6603.  
  6604.      EXAMPLE
  6605.  
  6606.      ;NOTE that this example is only meant to illustrate the GETFNAME command
  6607.      ; and you could accomplish much the same thing by using a single UPLOAD
  6608.      ; command, without specifying the filenames to upload.  When this is the
  6609.      ; case, UPLOAD prompts the user to enter filenames just as when you 
  6610.      ; press [PgUp] when online, and the user could also press [Alt-F] to
  6611.      ; enter the Upload File Picker (which does the same thing as below).
  6612.  
  6613.      variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST
  6614.      variable lst                              ;file handle for GETFNAME.LST
  6615.      variable s                                ;general purpose
  6616.  
  6617.      stritem s $UL_PATH 1                      ;store 1st dir on U/L PATH in s
  6618.  
  6619.      GETFNAME s "" "Please ^"Select^" one or more files to upload"
  6620.      notexist lstname goto skip_ul
  6621.  
  6622.      strins lstname "@" 0 1                    ;@C:\ICOM\GETFNAME.LST
  6623.      upload "Z" lstname                        ;uploads all files on the list
  6624.      strdel lstname 0 1                        ;kill the @ (position 0, 1
  6625.      char)
  6626.  
  6627.      ;This below illustrates how to extract each filename separately from
  6628.      ; GETFNAME.LST.  We only PRINT the filenames below (which are stored
  6629.      ; in 's' by FGETS), but you'd be free to do whatever you wanted with
  6630.  
  6631.  
  6632.  
  6633.  
  6634.      Intellicomm v2.01               SCRIPT.DOC                            102
  6635.      
  6636.      
  6637.  
  6638.      ; the filename(s), including FOPENing the file, DELETEing it, etc.
  6639.  
  6640.      if $ERRORLEVEL = 0           ;set by UPLOAD if successful
  6641.       print "Files uploaded:" 
  6642.       fopen lst lstname "r"       ;open GETFNAME.LST for "r"eading
  6643.       while 1                     ;endless loop (until BREAK)
  6644.        fgets s lst                ;get first/next line from GETFNAME.LST
  6645.        if $ERRORLEVEL <> 0 BREAK  ;exit loop at end of file (set by FGETS)
  6646.        print s                    ;do whatever you like with each file
  6647.       endwhile
  6648.       fclose lst                  ;always close what you FOPEN
  6649.      endif
  6650.  
  6651.      delete lstname               ;not necessary, but nice to keep it clean
  6652.      skip_ul:
  6653.       return
  6654.  
  6655.      GETS_____________________________________________________________________
  6656.      GETSXY___________________________________________________________________
  6657.  
  6658.      SUMMARY
  6659.  
  6660.       GETS vINPUT nMAXLEN
  6661.       GETSXY vINPUT nMAXLEN [nX] [nY] [nCOLOR]
  6662.  
  6663.      DESCRIPTION
  6664.  
  6665.       Both commands get user input from the keyboard, a maximum of nMAXLEN
  6666.       characters long, and store the result in variable vINPUT.  If variable
  6667.       vINPUT contains any data, it is offered to the user as a default value. 
  6668.       I.e. if you do not wish to offer a default, you must clear the vINPUT
  6669.       variable if it was used previously:
  6670.  
  6671.        assign myvariable ""   ;clear variable 'myvariable'
  6672.        GETS myvariable 10     ;get up to 10 characters of input
  6673.  
  6674.       GETS obtains the input at the current cursor position ($SCRN_Y,
  6675.       $SCRN_Y), while GETSXY obtains input at specific screen X,Y coordinates
  6676.       (nX, nY parameters above).  Both nX and nY are optional and if both
  6677.       coordinates are omitted, the input is obtained at the current cursor
  6678.       position (as with GETS).  If only the nX (screen column, left to right)
  6679.       position is specified, $SCRN_Y (the current cursor row) is used.
  6680.  
  6681.       Both commands get input and display the input 'field' in a specific
  6682.       color, showing the maximum length (nMAXLEN) of the input field.  GETS
  6683.       uses the $BAR_COLOR color (as with most Intellicomm input fields) as
  6684.       does GETSXY if the [nCOLOR] parameter is omitted.  If you specify
  6685.       [nCOLOR] with GETSXY (or if you temporarily change $BAR_COLOR prior to
  6686.       using either GETS or GETSXY), you can display an input field using
  6687.       another color.  See the COLOR CODES Appendix for information on creating
  6688.       custom color codes.
  6689.  
  6690.       GETS and GETSXY use the same input routine that BOXGETS uses, but they
  6691.       don't display a box or prompt (>) character.  Please see the BOXGETS
  6692.  
  6693.  
  6694.  
  6695.  
  6696.      Intellicomm v2.01               SCRIPT.DOC                            103
  6697.      
  6698.      
  6699.  
  6700.       description for more details on cursor keys and hotkeys available to the
  6701.       user when entering input, and an example of checking $ERRORLEVEL after
  6702.       the user input (Esc key pressed, etc).
  6703.  
  6704.      ERRORLEVEL
  6705.  
  6706.       0   The user entered something then pressed the [Enter] key or left
  6707.           mouse button (variable vINPUT contains data).
  6708.       1   The user pressed [Enter], but variable vINPUT is empty ... nothing
  6709.           was entered.
  6710.       2   The user pressed the [Esc] key or right mouse button to cancel.  If
  6711.           this occurs, the contents of vINPUT reverts to its original value 
  6712.           (the default you offered) whether the user changed it on the input
  6713.           line or not.
  6714.      256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns,
  6715.           the user pressed a key defined in one of the $HOTKEY_? variables. 
  6716.           See the BOXGETS example for details.
  6717.  
  6718.      SEE ALSO
  6719.  
  6720.       BOXGETS, INKEY
  6721.  
  6722.      EXAMPLE
  6723.  
  6724.       variable myvariable            ;define a variable called 'myvariable'
  6725.  
  6726.       assign myvariable "Default Response"  ;give the user a default
  6727.       printnc "Enter your response: "       ;print, no CR
  6728.       GETS myvariable 30                    ;30 chars max
  6729.       printnc "You entered: "
  6730.       print myvariable
  6731.       
  6732.        ;this bit below gets user input on the status line (similar to the
  6733.        ; way Icom prompts for a new capture file when you press [Alt-L])
  6734.  
  6735.       assign $STAT_ON 0                     ;turn the status line off
  6736.       scroll 1 $SCRN_HEIGHT $SCRN_WIDTH $SCRN_HEIGHT 0 $STAT_COLOR
  6737.        ;draws a blank line in the usual status bar color, on the bottom
  6738.        ; screen line
  6739.       printraw 1 $SCRN_HEIGHT $STAT_COLOR "Enter your response:"
  6740.       GETSXY myvariable 80 22 $SCRN_HEIGHT $STAT_COLOR  ;on the status line
  6741.       
  6742.       assign $STAT_ON 1                     ;restore status line
  6743.  
  6744.      GOSUB____________________________________________________________________
  6745.      RETURN___________________________________________________________________
  6746.  
  6747.      SUMMARY
  6748.  
  6749.       GOSUB LABEL
  6750.  
  6751.      DESCRIPTION
  6752.  
  6753.       GOSUB/RETURN work as a team and allow you to execute a set of script
  6754.  
  6755.  
  6756.  
  6757.  
  6758.      Intellicomm v2.01               SCRIPT.DOC                            104
  6759.      
  6760.      
  6761.  
  6762.       commands, then continue where you came from.  While GOTO simply jumps to
  6763.       a label without returning, GOSUB jumps to the label, then RETURNs to the
  6764.       command(s) following the GOSUB, if any.  One exception is when GOSUB is
  6765.       used in a WHEN command.  In that case, control returns to the WAITFOR
  6766.       if/when a RETURN is found (see the example below).
  6767.  
  6768.       NOTE: If Icom runs across a RETURN command and has not previously
  6769.       executed a GOSUB command, the script simply ends at that point (RETURN
  6770.       is the usual command to exit a script).
  6771.  
  6772.       NOTE FOR ADVANCED SCRIPT WRITERS: GOSUB can also jump to a label using a
  6773.       variable.  Just store the label's name in the variable, then specify the
  6774.       variable preceded by an asterisk:
  6775.  
  6776.        variable label "some_label"
  6777.  
  6778.        gosub *label    ;same as 'gosub some_label'
  6779.  
  6780.        some_label:
  6781.  
  6782.      SEE ALSO
  6783.  
  6784.       GOTO
  6785.  
  6786.      EXAMPLE
  6787.  
  6788.       GOSUB initialize_script  ;jump to label 'initialize_script:'
  6789.                                ;control returns to this line after the RETURN
  6790.       send "Some Command"
  6791.       waitfor main_menu 120    
  6792.  
  6793.       when
  6794.       when "some prompt" gosub handle_some_prompt
  6795.       when "another prompt" "do this"
  6796.       waitfor main_menu 120    ;control returns to WAITFOR after the GOSUB
  6797.  
  6798.       RETURN                   ;exit script (no GOSUB is active)
  6799.  
  6800.      initialize_script:        ;subroutine labels are the same as GOTO labels
  6801.  
  6802.        ;define a variable for use later in the script
  6803.       variable main_menu
  6804.       getbif main_menu "L" "mnap"    ;BIF [L]ogon section, Main Menu A prompt
  6805.       RETURN                   ;return from the subroutine
  6806.  
  6807.      handle_some_prompt:
  6808.       ... ;any number of commands can be placed here to handle what needs
  6809.      doing
  6810.       RETURN
  6811.  
  6812.      GOTO_____________________________________________________________________
  6813.  
  6814.      SUMMARY
  6815.  
  6816.  
  6817.  
  6818.  
  6819.      Intellicomm v2.01               SCRIPT.DOC                            105
  6820.      
  6821.      
  6822.  
  6823.       GOTO LABEL
  6824.  
  6825.      DESCRIPTION
  6826.  
  6827.       Jumps to the label specified by LABEL (a colon is not needed after
  6828.       LABEL, but is acceptable).  GOTO is used to skip over a portion of a
  6829.       script when a certain condition warrants it.
  6830.  
  6831.       Script labels are covered in the introduction of SCRTUTOR.DOC.
  6832.  
  6833.       NOTE FOR ADVANCED SCRIPT WRITERS: GOTO can also jump to a label using a
  6834.       variable.  Just store the label's name in the variable, then specify the
  6835.       variable preceded by an asterisk:
  6836.  
  6837.        variable label "some_label"
  6838.  
  6839.        goto *label    ;same as 'goto some_label'
  6840.  
  6841.        some_label:
  6842.  
  6843.      SEE ALSO
  6844.  
  6845.       GOSUB
  6846.  
  6847.      EXAMPLE
  6848.  
  6849.       online GOTO skip_logon  ;skip dial/logon if have a connection
  6850.  
  6851.       dial "Favorite BBS" 1
  6852.       waitfor "name:"
  6853.       send "Joe Smith"
  6854.       ...etc.
  6855.  
  6856.      skip_logon:
  6857.  
  6858.       send "D SOMEFILE.ZIP Z"
  6859.       download ""
  6860.       hangup
  6861.       return
  6862.  
  6863.      GOTOXY___________________________________________________________________
  6864.  
  6865.      SUMMARY
  6866.  
  6867.       GOTOXY nX nY
  6868.  
  6869.      DESCRIPTION
  6870.  
  6871.       Moves the cursor to screen column nX (left to right), row nY (top to
  6872.       bottom).  The top left corner of the screen is 1 1.
  6873.  
  6874.       If WINDOW or WNDOPEN are currently in effect, the top corner of the
  6875.       WINDOW ($WND_LEFT, $WND_TOP) represents screen coordinate 1 1, instead
  6876.       of the actual top of the video display.
  6877.  
  6878.  
  6879.  
  6880.  
  6881.      Intellicomm v2.01               SCRIPT.DOC                            106
  6882.      
  6883.      
  6884.  
  6885.      SEE ALSO
  6886.  
  6887.       CURPUSH, CURPOP
  6888.  
  6889.      EXAMPLE
  6890.  
  6891.       GOTOXY 1 1
  6892.       print "This is displayed at the top of the screen, or the top of the"
  6893.       print "current WINDOW (if any)."
  6894.  
  6895.      HANGUP___________________________________________________________________
  6896.  
  6897.      SUMMARY
  6898.  
  6899.       HANGUP
  6900.  
  6901.      DESCRIPTION
  6902.  
  6903.       Causes the modem to disconnect.  If the main setup item "Drop DTR to
  6904.       Hangup?" (*dtrhangup) is set to Yes, HANGUP drops the DTR (Data Terminal
  6905.       Ready) line for 1.5 seconds, delays for 0.5 seconds, then checks the
  6906.       carrier status.  If still connected (or if "Drop DTR to Hangup" was set
  6907.       to No) the main setup "Modem Hangup String" (normally +++ATH0) is then
  6908.       sent to the modem.
  6909.  
  6910.       Note that HANGUP ignores the main setup "Confirm Hangup?" option which
  6911.       asks the user for confirmation before hanging up.  You can easily
  6912.       simulate your own 'Hangup?  Yes  No' menu with these commands:
  6913.  
  6914.       IF *hconfirm = 0            ;Confirm Hangup variable set to NO (0)?
  6915.        HANGUP
  6916.       ELSE
  6917.        MENUDEFINE "~Yes" "~No"    ;define a Yes/No menu
  6918.        MENUBOXH "" "^IHangup?"    ;^I (TAB) puts help on same line as menu
  6919.        IF $ERRORLEVEL = 1 HANGUP  ;if "Yes" (item 1) then hang up
  6920.       ENDIF
  6921.  
  6922.       This gives the exact same menu in a box that the main setup "Confirm
  6923.       Hangup?" option does.
  6924.  
  6925.      ERRORLEVEL
  6926.  
  6927.       0  Successful (disconnected).
  6928.       1  Unsuccessful (modem reports still connected).  Note that if the modem
  6929.          is forcing the carrier detect signal on, HANGUP will always set
  6930.          $ERRORLEVEL 1 and will display a "Hangup Failed" message.  HANGUP
  6931.          checks the carrier detect before returning and if it's being forced
  6932.          on, Icom will always think it's connected (it has no other way of
  6933.          knowing, other than what the modem tells it).  This problem is quite
  6934.          common due to the way modems are configured from the factory, and the
  6935.          usual fixes are outlined in the "Common Questions & Answers" online
  6936.          help link.
  6937.  
  6938.      HELP_____________________________________________________________________
  6939.  
  6940.  
  6941.  
  6942.  
  6943.      Intellicomm v2.01               SCRIPT.DOC                            107
  6944.      
  6945.      
  6946.  
  6947.      SUMMARY
  6948.  
  6949.       HELP [sHELPLINK]
  6950.  
  6951.      DESCRIPTION
  6952.  
  6953.       If sHELPLINK is omitted the Help Index is displayed.  If sHELPLINK is
  6954.       specified, all .HLP files are searched for the link and, if found, the
  6955.       topic is displayed.  Specify sHELPLINK exactly as you see it in the
  6956.       online help system (see example).
  6957.  
  6958.      ERRORLEVEL
  6959.  
  6960.       0  sHELPLINK was found and displayed
  6961.       1  sHELPLINK not found
  6962.  
  6963.      SEE ALSO
  6964.  
  6965.       HELPFIND
  6966.  
  6967.      EXAMPLE
  6968.  
  6969.       HELP "Script Language"  ;display the Script Language link
  6970.  
  6971.      HELPFIND_________________________________________________________________
  6972.  
  6973.      SUMMARY
  6974.  
  6975.       HELPFIND sSEARCHTEXT
  6976.  
  6977.      DESCRIPTION
  6978.  
  6979.       Similar to pressing [Ctrl-F1] (Search) in the help system.  Searches all
  6980.       help topics for the text sSEARCHTEXT, writes all links containing the
  6981.       text to the file SEARCH.HLP, then displays the file SEARCH.HLP (all the
  6982.       links found, if any) for selection/viewing.
  6983.  
  6984.      ERRORLEVEL
  6985.  
  6986.       0  sSEARCHTEXT was found and SEARCH.HLP was displayed.
  6987.       1  sSEARCHTEXT was not found.
  6988.  
  6989.      SEE ALSO
  6990.  
  6991.       HELP
  6992.  
  6993.      EXAMPLE
  6994.  
  6995.       HELPFIND "script"  ;find all topics containing the word 'script'
  6996.                          ; and display them
  6997.       
  6998.        ;Later in your script you can display the results of the previous
  6999.        ; HELPFIND by using:
  7000.  
  7001.  
  7002.  
  7003.  
  7004.      Intellicomm v2.01               SCRIPT.DOC                            108
  7005.      
  7006.      
  7007.  
  7008.       HELP "Search Results"
  7009.  
  7010.      IF_____________________________________________________________________
  7011.       ELSE__________________________________________________________________
  7012.       ENDIF_________________________________________________________________
  7013.  
  7014.      SUMMARY
  7015.  
  7016.       IF ITEM1 OPERATOR ITEM2 [cCOMMAND]
  7017.        [cCOMMAND]
  7018.        ...
  7019.       [ELSE]
  7020.        [cCOMMAND]
  7021.        ...
  7022.       [ENDIF]
  7023.  
  7024.      DESCRIPTION
  7025.  
  7026.       IF compares ITEM1 and ITEM2 according to OPERATOR and if the comparison
  7027.       is true it executes the cCOMMAND parameter on the same line as the IF
  7028.       command (if specified), or skips cCOMMAND if the comparison is false. 
  7029.       If a cCOMMAND parameter is given on the same line as the IF statement,
  7030.       you *cannot* use ELSE or ENDIF.  If no cCOMMAND is given on the same
  7031.       line as the IF command, an IF/ENDIF sequence is assumed and the ENDIF
  7032.       becomes mandatory.  IF/ENDIF is used to execute a SET of commands (as
  7033.       opposed to a single command) and this sequence either:
  7034.  
  7035.        -  executes the command(s) (if any) between IF and ELSE if the
  7036.           comparison is true.
  7037.  
  7038.       OR (ELSE)
  7039.  
  7040.        -  executes the command(s) between ELSE (if specified) and ENDIF if the
  7041.           comparison is FALSE.  If no ELSE is specified, and the condition is
  7042.           false, control is passed to the script command following the ENDIF.
  7043.  
  7044.       The square brackets in the summary denote OPTIONAL items, and should not
  7045.       be used in your script.  ENDIF is only optional if the cCOMMAND
  7046.       parameter is specified on the same line as the IF.  The '...' simply
  7047.       means that more of the same (more commands) can follow.
  7048.  
  7049.       The OPERATOR parameter can be one of the following:
  7050.  
  7051.       OPERATOR      MEANING
  7052.       ---------------------------------------------------------------------
  7053.          =          Equal to
  7054.          <>         Not equal to
  7055.          <          Less than
  7056.          <=         Less than or equal to
  7057.          >          Greater than
  7058.          >=         Greater than or equal to (=> is not valid)
  7059.  
  7060.       If you plan to use variables with IF, only ITEM1 and/or ITEM2 can be
  7061.       variables.  For example, you cannot assign "<>" (Not equal to) to a
  7062.  
  7063.  
  7064.  
  7065.  
  7066.      Intellicomm v2.01               SCRIPT.DOC                            109
  7067.      
  7068.      
  7069.  
  7070.       variable and specify the variable as the OPERATOR parameter.  Nor could
  7071.       you assign the word "PRINT" to a variable and specify that variable as
  7072.       the cCOMMAND paremeter.  You CAN specify another IF as the cCOMMAND
  7073.       parameter:
  7074.  
  7075.        IF myvariable >= 1 IF myvariable <= 10 PRINT ">= 1 and <= 10" 
  7076.  
  7077.       If both ITEM1 and ITEM2 are numbers (variables or contants containing
  7078.       only characters from 0-9 ... surrounding quotes "" or '' are ignored)
  7079.       then a numeric comparison is performed and 1000 is greater than (>) 999,
  7080.       1 is less than (<) 2 as you'd expect.
  7081.  
  7082.       If either ITEM1 or ITEM2 contain TEXT (characters other than 0-9) then a
  7083.       text or "ASCII" comparison is performed.  Text comparisons use the ASCII
  7084.       codes of each character, as outlined in the ASCII CODES Appendix.  One
  7085.       string will be 'greater than' another string if it contains a character
  7086.       with a higher ASCII code.  "B" is greater than "A", and "C" is greater
  7087.       than "B", "Yes" (which starts with a "Y") is greater than "No" (which
  7088.       starts with a "N"), etc.  The ASCII codes assign numbers to all the
  7089.       characters, and these numbers go in the order you'd expect when
  7090.       comparing alphabetic characters.  According to ASCII though, lowercase
  7091.       text is *greater than* UPPERCASE text.  If you compared "Icom" and
  7092.       "ICOM" ... "Icom" would be greater due to the lowercase "c".  The ASCII
  7093.       CODES Appendix shows you the numeric ASCII equivalent of each character
  7094.       so you can see which characters are greater than or less than others.
  7095.  
  7096.       Text comparisons won't be used with IF in a greater than/less than
  7097.       situation very often.  You'll normally want to see if one piece of text
  7098.       (perhaps something the user entered via the GETS command) is EQUAL TO
  7099.       (=) or NOT EQUAL TO (<> ... greater than or less than) some other text. 
  7100.       In order for your comparisons to be accurate, however, you must make
  7101.       sure you're comparing text that is the same case (both strings
  7102.       uppercase, or both lowercase).  The STRUPPER and STRLOWER commands
  7103.       convert text to uppercase/lowercase mainly for this purpose.
  7104.  
  7105.       If you get confused about whether to use < or > for greater than/less
  7106.       just think of them as arrows.  Greater than (>) points to the right ...
  7107.       there are a 'greater' number of right-handed people than there are left-
  7108.       handed people.  So >, which points towards your RIGHT hand is GREATER
  7109.       THAN.
  7110.  
  7111.       NOTE: You needn't indent the commands as was done above in the summary. 
  7112.       Indenting simply make the script more understandable, and also helps you
  7113.       to see that something is MISSING if you forget the ENDIF.  ENDIF is
  7114.       mandatory when IF is used, and your script will abort with an 'IF
  7115.       without ENDIF' error if you forget the ENDIF.
  7116.  
  7117.       TIP:  You can use the IF/ENDIF sequence on its own, OR with any script
  7118.       command that accepts another cCOMMAND as its parameter (EXIST, NOTEXIST,
  7119.       OFFLINE, ONLINE, WHEN, etc).
  7120.  
  7121.      ERRORLEVEL
  7122.  
  7123.       IF does not change $ERRORLEVEL.  The decision-making logic is built into
  7124.  
  7125.  
  7126.  
  7127.  
  7128.      Intellicomm v2.01               SCRIPT.DOC                            110
  7129.      
  7130.      
  7131.  
  7132.       the command.
  7133.  
  7134.      SEE ALSO
  7135.  
  7136.       WHILE/ENDWHILE
  7137.  
  7138.      EXAMPLE 1
  7139.       
  7140.       MENUDEFINE "~Yes" "~No"
  7141.       MENUBOXV "DELETING SOMEFILE.TXT" "Are you sure you want to do this?"
  7142.  
  7143.        ;MENUBOXV sets $ERRORLEVEL according to what the user selected.
  7144.        ; If $ERRORLEVEL = 1, the user selected "Yes" (menu item 1).  See the
  7145.        ; MENUBOXV summary for details.
  7146.  
  7147.       IF $ERRORLEVEL = 1 DELETE "SOMEFILE.TXT"
  7148.  
  7149.       variable Dog1 "DOG"
  7150.       variable Dog2 "Dog"
  7151.  
  7152.       strupper Dog2   ;convert "Dog" to "DOG" (all uppercase)
  7153.  
  7154.       IF Dog1 = Dog2 print "Dog1 and Dog2 are both the same."
  7155.  
  7156.        ;without the strupper to convert "Dog" (what Dog2 is initially
  7157.        ;assigned) to "DOG", the above would NOT be printed.
  7158.        
  7159.       assign Dog2 "CAT"  ;put the word CAT in 'Dog2'
  7160.  
  7161.        ;With "CAT" in Dog2, Dog1 is now GREATER THAN (>) Dog2
  7162.  
  7163.       IF Dog1 < Dog2  print "Would this be printed?"
  7164.  
  7165.        ;above, the print is ignored, since Dog1 is GREATER THAN (>)
  7166.        ;Dog2, not LESS THAN (<) Dog2
  7167.  
  7168.      EXAMPLE 2
  7169.  
  7170.       variable number    ;define a variable called 'number'
  7171.  
  7172.       printnc "Enter a number from 1 to 10: "
  7173.       gets number 2      ;2 is the max characters to get
  7174.  
  7175.       IF number <= 5 print "The number is less than or equal to 5."
  7176.       IF number > 5 print "The number is greater than 5."
  7177.       IF number = 10 print "The number is 10."
  7178.       IF number > 1 IF number < 10 print "The number is between 1 and 10."
  7179.  
  7180.         ;Example of 'nested' IFs
  7181.  
  7182.       IF number < 5 IF number = 1
  7183.                      print "The number is 1."
  7184.                     ELSE
  7185.                      printnc "The number is less than five and ... "
  7186.  
  7187.  
  7188.  
  7189.  
  7190.      Intellicomm v2.01               SCRIPT.DOC                            111
  7191.      
  7192.      
  7193.  
  7194.                      IF number = 2 print "The number is 2."
  7195.                      IF number = 3
  7196.                       print "The number is 3."
  7197.                      ELSE
  7198.                       print "The number is 4."
  7199.                      ENDIF
  7200.                     ENDIF
  7201.  
  7202.      EXAMPLE 3
  7203.       
  7204.       variable attempts  ;define variable 'attempts' (set to 0 automatically)
  7205.       variable success   ;define variable 'success'   ""             ""
  7206.  
  7207.       when "Name?"     send "John Smith"
  7208.       when "password?" IF attempts <= 3   ;if less than or equal to 3
  7209.                         send "mypassword" 
  7210.                         inc attempts      ;INCrement; attempts = attempts + 1
  7211.                        ELSE
  7212.                         stamp "Too many password failures."
  7213.                         goto LOGON_ERROR
  7214.                        ENDIF
  7215.       when "More?"     send "N"
  7216.       waitfor "Main Menu:" 120 LOGON_ERROR
  7217.  
  7218.       assign success 1      ;variable 'success' will be 1 if we found the
  7219.                             ; Main Menu: prompt, or will be 0 if we jumped
  7220.                             ; to LOGON_ERROR
  7221.  
  7222.      LOGON_ERROR:
  7223.       
  7224.       IF success = 1        ;if variable 'success' is equal to 1
  7225.        alarm
  7226.       ELSE
  7227.        stamp "Logon unsuccessful."
  7228.        hangup
  7229.       ENDIF
  7230.  
  7231.       return
  7232.  
  7233.      INC______________________________________________________________________
  7234.  
  7235.      SUMMARY
  7236.  
  7237.       INC vNUM
  7238.  
  7239.      DESCRIPTION
  7240.  
  7241.       Adds 1 to the contents of the variable vNUM (vNUM = vNUM + 1).
  7242.  
  7243.      SEE ALSO
  7244.  
  7245.       ADD, DEC
  7246.  
  7247.      EXAMPLE
  7248.  
  7249.  
  7250.  
  7251.  
  7252.      Intellicomm v2.01               SCRIPT.DOC                            112
  7253.      
  7254.      
  7255.  
  7256.       variable x 10   ;define 'x' and assign 10 to it
  7257.       inc x           ;increment the contents of 'x'
  7258.       print x         ;prints 11
  7259.  
  7260.  
  7261.      INITMODEM________________________________________________________________
  7262.  
  7263.      SUMMARY
  7264.  
  7265.       INITMODEM
  7266.  
  7267.      DESCRIPTION
  7268.  
  7269.       Displays a message to the user, flushes the send/transmit buffers
  7270.       (RXFLUSH, TXFLUSH) sends the main setup "Initialize Modem" string to the
  7271.       modem (*minit variable), then waits for 1.5 seconds for the COM port DCD
  7272.       (carrier detect) signal to return to normal.  Some modems fluctuate the
  7273.       COM port online/offline status after an ATZ (reset) command, which is
  7274.       often used in modem init strings... and this can cause Intellicomm to
  7275.       think that a connection was established then lost.  Thus, INITMODEM
  7276.       waits for the modem to settle down before returning to Intellicomm.
  7277.  
  7278.       Note that your modem must be in "command state" or it will simply send
  7279.       the Initialize Modem string over the telephone line (to the BBS) if
  7280.       you're already online.  You can activate command state on most modems by
  7281.       sending three plus signs and waiting for a second or two.  See the
  7282.       example below for more details.
  7283.  
  7284.      ERRORLEVEL
  7285.  
  7286.      SEE ALSO
  7287.  
  7288.      EXAMPLE
  7289.  
  7290.        if $carrier = 0   ;offline?  No problem
  7291.         INITMODEM
  7292.        else
  7293.          ;This may or may not work... it depends on the modem.  It's
  7294.          ; provided more for demonstration purposes than anything.  It
  7295.          ; really shouldn't be necessary to re-initialize the modem while
  7296.          ; online.
  7297.         send "+++~"      ;put modem into command state
  7298.         INITMODEM        ;send the init string
  7299.         send "ATO"       ;return to online state (exit command state)
  7300.        endif
  7301.  
  7302.      INKEY____________________________________________________________________
  7303.      INKEYT___________________________________________________________________
  7304.      INKEYW___________________________________________________________________
  7305.  
  7306.      SUMMARY
  7307.  
  7308.       INKEY vKEYCODE
  7309.       INKEYW vKEYCODE
  7310.  
  7311.  
  7312.  
  7313.  
  7314.      Intellicomm v2.01               SCRIPT.DOC                            113
  7315.      
  7316.      
  7317.  
  7318.       INKEYT vKEYCODE nTIMEOUT
  7319.  
  7320.      DESCRIPTION
  7321.  
  7322.       These commands get a single key stroke from the keyboard and store its
  7323.       code (see Keyboard Codes Appendix) in vKEYCODE.
  7324.  
  7325.       IMPORTANT NOTE:  If you plan to use any of the above commands, you must
  7326.       first set $KEY_CHECK to 0 (shut off regular terminal mode key checks),
  7327.       or the script processor will eat most of the keystrokes before INKEY/W/T
  7328.       gets to them.  This is more important with INKEY than it is for INKEYW
  7329.       or INKEYT, since INKEY doesn't WAIT for a keypress: it just makes a
  7330.       quick check of the keystroke buffer.  Example:
  7331.  
  7332.        variable key
  7333.  
  7334.        assign $KEY_CHECK 0       ;shut off regular keyboard checking
  7335.        while 1
  7336.         INKEY key                ;this now gets EVERY keystroke
  7337.         if key = "^[" break      ;[Esc] pressed?   
  7338.        endwhile
  7339.        assign $KEY_CHECK 1       ;always turn it back on when you're done
  7340.  
  7341.       Note that the key needn't actually be physically pressed at the time
  7342.       that INKEY is called ...  IBM PC's (XT/AT/386/486,etc) buffer keystrokes
  7343.       in internal memory locations called the "keyboard buffer" when the user
  7344.       actually presses a key (where the keycode is saved even after the key is
  7345.       released), and INKEY/INKEYW/INKEYT simply check the keyboard buffer.  So
  7346.       you needn't worry about "timing" your use of INKEY/INKEYW/INKEYT with
  7347.       the user's actual key presses.  On the other hand, if you don't WANT the
  7348.       buffered keystrokes (there's no way to tell how old they are), call
  7349.       KBFLUSH to flush the keyboard buffer, just after you ask for input:
  7350.  
  7351.        print "Press a key..."
  7352.        KBFLUSH                 ;ensures no "old" keystrokes take effect
  7353.        INKEYW key
  7354.  
  7355.       INKEY quickly checks the keyboard buffer for any pressed keys.  If a new
  7356.       keycode is waiting, its value is stored in vKEYCODE.  Otherwise 0 (zero)
  7357.       is stored in vKEYCODE.  You'll use this variation when you want to check
  7358.       for keys WHILE doing something else (displaying information on the
  7359.       screen, etc) at the same time, as illustrated just above in the WHILE
  7360.       loop.
  7361.  
  7362.       INKEYW waits for a key press (if no keys are waiting in the keyboard
  7363.       buffer when it's called).  Your script does not continue until the user
  7364.       has actually pressed a key, at which point the key pressed will be
  7365.       stored in vKEYCODE, and the script will continue.
  7366.  
  7367.       INKEYT is an INKEYW with a timeout (specified in tenths of a second). 
  7368.       It waits for nTIMEOUT tenths of a second for a key press.  If a key is
  7369.       pressed (or is waiting in the keyboard buffer when INKEYT is called), it
  7370.       immediately stores the keycode in vKEYCODE and returns.  If no key is
  7371.       pressed within nTIMEOUT tenths of a second, INKEYT returns (your script
  7372.  
  7373.  
  7374.  
  7375.  
  7376.      Intellicomm v2.01               SCRIPT.DOC                            114
  7377.      
  7378.      
  7379.  
  7380.       continues execution) and vKEYCODE will be 0 (zero).
  7381.  
  7382.       Please see the KEYBOARD CODES appendix for a list of all keyboard codes.
  7383.  
  7384.      ERRORLEVEL
  7385.  
  7386.       None of these commands set $ERRORLEVEL.  You can get all the information
  7387.       you need by checking the vKEYCODE variable you specify.  For a list of
  7388.       key codes, see KEYBOARD CODES in the online help and/or SCRIPT.DOC.
  7389.  
  7390.      SEE ALSO
  7391.  
  7392.       BOXGETS, GETS, $KEY_ALTQ, $KEY_CHECK
  7393.  
  7394.      EXAMPLE
  7395.  
  7396.       variable keycode     ;always need a variable to store codes in
  7397.  
  7398.       printnc "Press a key, or [Esc] to abort: "
  7399.       INKEYW keycode
  7400.       if keycode = "^[" exit
  7401.  
  7402.       printnc "Press a key: "
  7403.       INKEYT keycode 100   ;ends the pause after 10 seconds if no key pressed
  7404.  
  7405.         ;This bit below updates an on-screen clock where [Alt-Z] for Menu is
  7406.         ; usually displayed on the status line, while also processing user
  7407.         ; keystrokes.
  7408.  
  7409.       variable cur_sec
  7410.       variable last_sec -1
  7411.  
  7412.         ;first erase "Alt-Z for Menu" on the status line (bottom screen line)
  7413.       scroll 66 $SCRN_HEIGHT 80 $SCRN_HEIGHT 0 $STAT_COLOR
  7414.       
  7415.       while 1              ;endless loop (until BREAK)
  7416.        INKEY keycode       ;keep going if nothing there
  7417.        if keycode = "^[" break
  7418.  
  7419.         ;we only want to update the clock once per second, or it will flicker
  7420.        substr cur_sec $TIME 7 1    ;HH:MM:SS .. gets the last 'S' (second)
  7421.      char
  7422.        if cur_sec = last_sec continue
  7423.        assign last_sec cur_sec
  7424.        printraw 69 $SCRN_HEIGHT $STAT_COLOR $TIME
  7425.       endwhile
  7426.  
  7427.       assign $STAT_ON 0    ;re-draw the original status line
  7428.       assign $STAT_ON 1
  7429.  
  7430.      KBFLUSH__________________________________________________________________
  7431.  
  7432.      SUMMARY
  7433.  
  7434.  
  7435.  
  7436.  
  7437.      Intellicomm v2.01               SCRIPT.DOC                            115
  7438.      
  7439.      
  7440.  
  7441.       KBFLUSH
  7442.  
  7443.      DESCRIPTION
  7444.  
  7445.       When the user presses keys on the keyboard, the computer stores the key
  7446.       code(s) in the "keyboard buffer".  The keys will sit in this buffer
  7447.       until Intellicomm or your script actually gets it/them one by one with
  7448.       INKEY, INKEYW, INKEYT, or a menu function (MENUBAR, MENUBOXH, MENUBOXV),
  7449.       or GETS, BOXGETS (though GETS/BOXGETS automatically call KBFLUSH on
  7450.       entry).  If there's a critical error message or the like you must
  7451.       display to the user though, and you want to ensure that some previous
  7452.       keystroke doesn't bypass the message, you can call KBFLUSH to flush any
  7453.       existing keystrokes from the keystroke buffer.  Key strokes wait in the
  7454.       keyboard buffer INDEFINITELY, until you call KBFLUSH or one of the
  7455.       INKEY.. / or MENU.. functions.
  7456.  
  7457.      SEE ALSO
  7458.  
  7459.       INKEY, INKEYT, INKEYW
  7460.  
  7461.      EXAMPLE
  7462.  
  7463.       printnc "Are you sure? "
  7464.       menudefine "~Yes" "~No"
  7465.       KBFLUSH
  7466.       menubar
  7467.  
  7468.      LIST_____________________________________________________________________
  7469.  
  7470.      SUMMARY
  7471.  
  7472.       LIST sFILENAME [nLINENUM]
  7473.  
  7474.      DESCRIPTION
  7475.  
  7476.       Enters Icom's internal File Viewer, or the external viewer defined by
  7477.       the user (main setup/Filenames and Paths screen, main setup variable
  7478.       *flister).
  7479.  
  7480.       sFILENAME is the file to view ([D:][\PATH\]FILENAME[.EXT] a filename
  7481.       with optional drive, path and extension).
  7482.  
  7483.       nLINENUM is only valid when *flister is blank (no external viewer), and
  7484.       it specifies an optional line number to position to after loading
  7485.       sFILENAME.
  7486.  
  7487.       NOTE: If you want to ensure use of Icom's internal File Viewer, simply
  7488.       save the *flister main setup variable, clear it, then call LIST. 
  7489.       Example:
  7490.  
  7491.       variable filename $HOME_DIR "SCRTUTOR.DOC"
  7492.       variable oldlister *flister ;save external viewer (if any)
  7493.       
  7494.       assign *flister ""          ;clear external viewer
  7495.  
  7496.  
  7497.  
  7498.  
  7499.      Intellicomm v2.01               SCRIPT.DOC                            116
  7500.      
  7501.      
  7502.  
  7503.       LIST filename 100           ;list C:\ICOM\SCR\SCRTUTOR.DOC position to
  7504.                                   ; line 100
  7505.       assign *flister oldflister  ;restore original external editor
  7506.  
  7507.       This should only be done when you must seek to a specific line number in
  7508.       a file.  You should otherwise let the user view files in his preferred
  7509.       external file viewer.
  7510.  
  7511.      SEE ALSO
  7512.  
  7513.       EDIT
  7514.  
  7515.      EXAMPLE
  7516.  
  7517.       variable filename $HOME_DIR "SCRIPT.DOC"
  7518.       
  7519.       pause "Press a key to view SCRIPT.DOC..."
  7520.       LIST filename
  7521.  
  7522.      LOADBIF__________________________________________________________________
  7523.  
  7524.      SUMMARY
  7525.  
  7526.       LOADBIF sBIFNAME
  7527.  
  7528.      DESCRIPTION
  7529.  
  7530.       Loads the BBS Information File (.BIF) sBIFNAME into memory.  Neither the
  7531.       .BIF extension nor the C:\ICOM\BIF directory should be specified: just
  7532.       the BIF filename.
  7533.  
  7534.       BIFs are completely useless on-disk.  The only way they can be used is
  7535.       to load them into memory.  Icom loads BIFs into memory on its own when
  7536.       dialing, after connecting to a BBS, when importing new files lists, and
  7537.       for various other purposes.  You can do the same from your scripts by
  7538.       using LOADBIF and the various BIF Variables outlined in the BIF
  7539.       VARIABLES Appendix of this manual.
  7540.  
  7541.      ERRORLEVEL
  7542.  
  7543.       0  sBIFNAME is loaded.
  7544.       1  Unable to load sBIFNAME (file not found).
  7545.  
  7546.      SEE ALSO
  7547.  
  7548.       SAVEBIF
  7549.  
  7550.      EXAMPLE
  7551.  
  7552.       LOADBIF "ICOM"  ;load the BIF for the Icom Online Service
  7553.  
  7554.      LOADINI__________________________________________________________________
  7555.  
  7556.      SUMMARY
  7557.  
  7558.  
  7559.  
  7560.  
  7561.      Intellicomm v2.01               SCRIPT.DOC                            117
  7562.      
  7563.      
  7564.  
  7565.       LOADINI sININAME
  7566.  
  7567.      DESCRIPTION
  7568.  
  7569.       Loads the Main Initialization File (.INI) sININAME into memory.  Neither
  7570.       the .INI extension nor the C:\ICOM directory should be specified: just
  7571.       the INI filename.
  7572.  
  7573.       INI files are completely useless on-disk.  The only way they can be used
  7574.       is to load them into memory.  Icom loads ICOM.INI (the default main
  7575.       setup file) into memory on its own at program startup.  You can later
  7576.       load other main setup files from your scripts by using LOADINI and the
  7577.       various Main Setup Variables outlined in the MAIN SETUP VARIABLES
  7578.       Appendix of this manual.
  7579.  
  7580.      ERRORLEVEL
  7581.  
  7582.       0  sININAME is loaded.
  7583.       1  Unable to load sININAME (file not found normally).
  7584.  
  7585.      SEE ALSO
  7586.  
  7587.       SAVEINI
  7588.  
  7589.      EXAMPLE
  7590.  
  7591.       LOADINI "CUSTOM"  ;load the CUSTOM.INI file settings
  7592.  
  7593.      LOCATEFILE_______________________________________________________________
  7594.  
  7595.      SUMMARY
  7596.  
  7597.       LOCATEFILE vBUFFER sFILESPEC ...
  7598.  
  7599.      DESCRIPTION
  7600.  
  7601.       LOCATEFILE searches for sFILESPEC.  If an explicit D:\PATH is specified
  7602.       in sFILESPEC, only the specified directory is searched.  If no directory
  7603.       is specified, LOCATEFILE searches all directories on the Upload PATH,
  7604.       the Download Directory, and (if the Main Setup variable *pathsch is non-
  7605.       zero) all directories on the DOS PATH.  If the file is found, its full
  7606.       D:\PATH\FILENAME.EXT is stored in variable vBUFFER.
  7607.  
  7608.       sFILESPEC specifies the file to search for.  DOS wildcard characters *
  7609.       and ? are accepted, and, as mentioned above, you may specify an optional
  7610.       D:\PATH to search in a specific directory.
  7611.  
  7612.       NOTE: LOCATEFILE does not locate directories or hidden files (it's meant
  7613.       to be used to locate files for uploading, and neither directories nor
  7614.       hidden files can be uploaded).  Use FINDFIRST to locate these.
  7615.  
  7616.      ERRORLEVEL
  7617.  
  7618.       0  sFILESPEC was found and the full D:\PATH\FILENAME.EXT has been stored
  7619.  
  7620.  
  7621.  
  7622.  
  7623.      Intellicomm v2.01               SCRIPT.DOC                            118
  7624.      
  7625.      
  7626.  
  7627.          in vBUFFER.
  7628.       1  sFILESPEC was not found.  Try using DISKFIND if appropriate.
  7629.  
  7630.      SEE ALSO
  7631.  
  7632.       EXIST, FINDFIRST, DISKFIND
  7633.  
  7634.      EXAMPLE
  7635.  
  7636.       variable file
  7637.  
  7638.       LOCATEFILE file "ICOM201A.ZIP"
  7639.       if $errorlevel = 0 upload "Z" file
  7640.  
  7641.      LOG______________________________________________________________________
  7642.  
  7643.      SUMMARY
  7644.  
  7645.       LOG [sLOGNAME]
  7646.  
  7647.      DESCRIPTION
  7648.  
  7649.       Opens the Usage Log.  If sLOGNAME is omitted, the default Usage Log
  7650.       filename (\ICOM\CAP\ICOM.USE, or the filename defined on the main setup
  7651.       Filenames and Paths screen) is assumed.  If the drive, path or extension
  7652.       is omitted in sLOGNAME the D:\PATH .EXT of the last Usage Log is
  7653.       assumed.
  7654.  
  7655.      SEE ALSO
  7656.  
  7657.       LOGCLOSE, STAMP
  7658.  
  7659.      EXAMPLE
  7660.  
  7661.       LOG "TEMP"    ;open a temporary usage log
  7662.  
  7663.  
  7664.      LOGCLOSE_________________________________________________________________
  7665.  
  7666.      SUMMARY
  7667.  
  7668.       LOGCLOSE
  7669.  
  7670.      DESCRIPTION
  7671.  
  7672.       Closes the Usage Log.
  7673.  
  7674.      SEE ALSO
  7675.  
  7676.       LOG, STAMP
  7677.  
  7678.      MENUBAR__________________________________________________________________
  7679.  
  7680.      SUMMARY
  7681.  
  7682.  
  7683.  
  7684.  
  7685.      Intellicomm v2.01               SCRIPT.DOC                            119
  7686.      
  7687.      
  7688.  
  7689.       MENUBAR nX nY [nSTART]
  7690.  
  7691.      DESCRIPTION
  7692.  
  7693.       Activates the last menu defined with MENUDEFINE in 'bar' format, at
  7694.       screen position nX (column, left to right), nY (row, top to bottom). 
  7695.       Menu items run horizontally from screen coordinates nX, nY, and no box
  7696.       is displayed around the menu.  If help is attached to a given menu item
  7697.       (with MENUHLP), its help text is displayed immediately under the first
  7698.       menu item when it is hilighted (as in the Icom Job Directory, BBS
  7699.       Directory bottom menus).
  7700.  
  7701.       If the optional nSTART parameter is specified, the current menu position
  7702.       (hilight) will be set to menu item # nSTART (1st menu option being item
  7703.       1, 2nd being item 2, etc) when the menu is first displayed.  I.e. this
  7704.       is the 'default' menu option.
  7705.  
  7706.      ERRORLEVEL
  7707.  
  7708.       MENUBAR does not set $ERRORLEVEL.  A separate variable called
  7709.       $MENUSELECTION is instead used to hold the last menu selection,
  7710.       undisturbed, from one menu use to the next.  After MENUBAR finishes
  7711.       $MENUSELECTION will be set to one of the following values:
  7712.  
  7713.       0  = [Esc] or right mouse button pressed (nothing selected).
  7714.       1+ = If $MENUSELECTION is 1 or greater, the user selected the
  7715.            corresponding menu item.  If set to 1, the user selected the first
  7716.            menu option.  Hidden or disabled menu items (see MENUITEMSTAT)
  7717.            still count as valid menu items.
  7718.  
  7719.      SEE ALSO
  7720.  
  7721.       MENUBOXH, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7722.  
  7723.      EXAMPLE
  7724.  
  7725.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7726.       examples of menu usage.
  7727.  
  7728.      MENUBOXH_________________________________________________________________
  7729.  
  7730.      SUMMARY
  7731.  
  7732.       MENUBOXH [sTITLE] [sHELPLINE] [nSTART]
  7733.  
  7734.      DESCRIPTION
  7735.  
  7736.       A picture is worth a thousand words.  MENUBOXH gives you the following
  7737.       (using graphics characters instead of +=), where "Item 1  Item2  Item3
  7738.       ..." is the last menu defined with the MENUDEFINE command:
  7739.  
  7740.                          +=| sTITLE |====================+
  7741.                          |                               |
  7742.                          |           sHELPLINE           |
  7743.  
  7744.  
  7745.  
  7746.  
  7747.                          Intellicomm v2.01SCRIPT.DOC                       120
  7748.      
  7749.      
  7750.  
  7751.                          |                               |
  7752.                          |  Item 1  Item 2  Item 3  ...  |
  7753.                          |                               |
  7754.                          +===============================+
  7755.  
  7756.       The box is displayed centered on the screen.  If the optional nSTART
  7757.       parameter is specified, the current menu position (hilight) will be set
  7758.       to menu item # nSTART (1st menu option being item 1, 2nd being item 2,
  7759.       etc) when the menu is first displayed.  I.e. nSTART is the 'default'
  7760.       menu option offered to the user.  If sTITLE or sHELPLINE is longer than
  7761.       the combined length of the menu items, the box will be adjusted
  7762.       accordingly.  If sHELPLINE is not specified the menu appears as follows:
  7763.  
  7764.                          +=| sTITLE |====================+
  7765.                          |                               |
  7766.                          |  Item 1  Item 2  Item 3  ...  |
  7767.                          |                               |
  7768.                          +===============================+
  7769.  
  7770.       You can also display sHELPLINE and the menu items all on the same line
  7771.       by using a TAB character as the first character in the sHELPLINE text. 
  7772.       Example (^I is a TAB):
  7773.  
  7774.         MENUDEFINE "~Yes" "~No"
  7775.         MENUBOXH "Title" "^IContinue?"
  7776.  
  7777.       This would give you the following:
  7778.  
  7779.                               +=| Title |============+
  7780.                               |                      |
  7781.                               |  Continue?  Yes  No  |
  7782.                               |                      |
  7783.                               +======================+
  7784.  
  7785.       It is UP TO YOU to ensure that the menu can be displayed properly.  If
  7786.       you define too many menu items to fit on the screen, or your help
  7787.       line/title is too long, the menu will be a mess.
  7788.  
  7789.      ERRORLEVEL
  7790.  
  7791.       MENUBOXH does not set $ERRORLEVEL.  A separate variable called
  7792.       $MENUSELECTION is instead used to hold the last menu selection,
  7793.       undisturbed, from one menu use to the next.  After MENUBOXH finishes
  7794.       $MENUSELECTION will be set to one of the following values:
  7795.  
  7796.       0   [Esc] or right mouse button pressed (nothing selected).
  7797.       1+  If $MENUSELECTION is 1 or greater, the user selected the
  7798.           corresponding menu item.  If set to 1, the user selected the first
  7799.           menu option, if 2 the second option was selected and so forth. 
  7800.           Hidden or disabled menu items (see MENUITEMSTAT) still count as
  7801.           valid menu items.
  7802.  
  7803.      SEE ALSO
  7804.  
  7805.  
  7806.  
  7807.  
  7808.      Intellicomm v2.01               SCRIPT.DOC                            121
  7809.      
  7810.      
  7811.  
  7812.       MENUBAR, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7813.  
  7814.      EXAMPLE
  7815.  
  7816.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7817.       examples of menu usage.
  7818.  
  7819.      MENUBOXV_________________________________________________________________
  7820.  
  7821.      SUMMARY
  7822.  
  7823.       MENUBOXV [sTITLE] [sHELPLINE] [nSTART]
  7824.  
  7825.      DESCRIPTION
  7826.  
  7827.       Displays the last menu defined with MENUDEFINE in 'vertical box' menu
  7828.       format, as follows:
  7829.  
  7830.                                   +=| sTITLE |==+
  7831.                                   |             |
  7832.                                   |  sHELPLINE  |
  7833.                                   |             |
  7834.                                   |   Item 1    |
  7835.                                   |   Item 2    |
  7836.                                   |   Item 3    |
  7837.                                   +=============+
  7838.  
  7839.       The box size is adjusted to fit the longest item, whether sTITLE,
  7840.       sHELPLINE, or one of the menu items is the longest.  The nSTART
  7841.       parameter is the optional menu item to hilight at menu startup (1 =
  7842.       hilight menu item 1, 2 = hilight menu item 2, etc).  If sHELPLINE is
  7843.       omitted, the menu is displayed as follows:
  7844.  
  7845.                                   +=| sTITLE |==+
  7846.                                   |             |
  7847.                                   |   Item 1    |
  7848.                                   |   Item 2    |
  7849.                                   |   Item 3    |
  7850.                                   +=============+
  7851.  
  7852.       When you plan to use MENUBOXV, you can also use menu "lines" in the
  7853.       menus you define.  Example:
  7854.  
  7855.        MENUDEFINE "Item ~1" "Item ~2" "-" "Item ~3" "Item ~4"
  7856.        MENUBOXV "
  7857.  
  7858.       The commands above would produce the following menu:
  7859.  
  7860.                                    +=| Title |=+
  7861.                                    |           |
  7862.                                    |  Item 1   |
  7863.                                    |  Item 2   |
  7864.                                    |-----------|
  7865.                                    |  Item 3   |
  7866.  
  7867.  
  7868.  
  7869.  
  7870.                                    Intellicomm v2.01SCRIPT.DOC             122
  7871.      
  7872.      
  7873.  
  7874.                                    |  Item 4   |
  7875.                                    +===========+
  7876.       
  7877.      ERRORLEVEL
  7878.  
  7879.       MENUBOXV does not set $ERRORLEVEL.  A separate variable called
  7880.       $MENUSELECTION is instead used to hold the last menu selection,
  7881.       undisturbed, from one menu use to the next.  After MENUBOXV finishes
  7882.       $MENUSELECTION will be set to one of the following values:
  7883.  
  7884.       0  = [Esc] or right mouse button pressed (nothing selected).
  7885.       1+ = If $MENUSELECTION is 1 or greater, the user selected the
  7886.            corresponding menu item.  If set to 1, the user selected the first
  7887.            menu option.  Hidden or disabled menu items (see MENUITEMSTAT)
  7888.            still count as valid menu items.  Menu lines do not count as menu
  7889.            items.
  7890.  
  7891.      SEE ALSO
  7892.  
  7893.       MENUBAR, MENUBOXH, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7894.  
  7895.      EXAMPLE
  7896.  
  7897.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7898.       examples of menu usage.
  7899.  
  7900.      MENUDEFINE_______________________________________________________________
  7901.  
  7902.      SUMMARY
  7903.  
  7904.       MENUDEFINE ITEM1 ITEM2 [ITEM3] ...
  7905.  
  7906.      DESCRIPTION
  7907.  
  7908.       Defines a list of two or more menu options for use with MENUBAR,
  7909.       MENUBOXH (horizontal menu options in a box) and MENUBOXV (vertical menu
  7910.       options in a box).  ITEM1 is the first menu option, ITEM2 is the second
  7911.       menu option, [ITEM3] ... is the third and following menu option(s) (the
  7912.       square brackets denote an optional item and should not be used).  A
  7913.       tilde (~) may (and should) be used within each ITEMx parameter to define
  7914.       the position of the item 'hotkey' (e.g. "~Yes" "~No").  The letter
  7915.       following the tilde will be displayed in 'bold' text, and can be used to
  7916.       select the menu option, once the menu is displayed, without moving the
  7917.       hilight bar.  Use of the tilde is optional, and if you omit a tilde the
  7918.       item will not have a hotkey.  If you're not careful, you can also
  7919.       inadvertantly assign the same hotkey to two different menu options.  If
  7920.       this happens, when the user presses the hotkey, the FIRST item that uses
  7921.       that hotkey will be selected.
  7922.  
  7923.       When using the MENUBOXH command (menu items are stacked on top of one
  7924.       another in a box) you can also use a single hypen as a menu option ("-")
  7925.       to specify a box divider line as you see on many of Icom's vertical box
  7926.       menus (e.g. MENUDEFINE "Item ~1" "-" "Item ~2").
  7927.  
  7928.  
  7929.  
  7930.  
  7931.      Intellicomm v2.01               SCRIPT.DOC                            123
  7932.      
  7933.      
  7934.  
  7935.       NOTE: No limits are enforced as to the number of options you can define
  7936.       with MENUDEFINE, but the screen size (and the type of menu you choose to
  7937.       use) may cause your menu to malfunction if you get out of hand with
  7938.       MENUDEFINE and define too many options.  Experience (trial and error) is
  7939.       the only reliable way to find the limits.  If you specify EGA/VGA
  7940.       extended line video modes (42/50 lines) in the Icom main setup, you can
  7941.       fit more menu options in a MENUBOXH (horizontal box) than you could on a
  7942.       25-line display.  Be sure to take this into account if you plan to
  7943.       distribute your scripts to others who may not have an EGA/VGA display.
  7944.       It's best to test your menus in 25-line video mode before distribution.
  7945.  
  7946.      SEE ALSO
  7947.       
  7948.       MENUBAR, MENUBOXH, MENUBOXV, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7949.  
  7950.      EXAMPLE
  7951.  
  7952.       MENUDEFINE "~Sure, no problem" "~No Thanks"
  7953.  
  7954.       if $DL_PROTOCOL = "Z" goto start  ;if the D/L protocol is Zmodem
  7955.       boxmenuh "Wrong Protocol!" "Okay to use Zmodem?"
  7956.       if $ERRORLEVEL <> 1 goto done     ;the user didn't select "Sure"
  7957.       assign $DL_PROTOCOL "Z"  ;change the D/L protocol to Zmodem
  7958.      start:
  7959.        ;main body of script here
  7960.  
  7961.      done:
  7962.       return      ;exit the script or subroutine
  7963.  
  7964.  
  7965.      MENUHLP__________________________________________________________________
  7966.  
  7967.      SUMMARY
  7968.  
  7969.       MENUHLP nMENUITEM nHELPTEXT
  7970.  
  7971.      DESCRIPTION
  7972.  
  7973.       Attaches the text nHELPTEXT to menu item number nMENUITEM.  A menu must
  7974.       be defined with MENUDEFINE before using MENUHLP.
  7975.  
  7976.       On bar menus (MENUBAR, MENUBOXH) the nHELPTEXT is displayed under the
  7977.       bar menu as each item is hilighted, similar to Intellicomm's Job
  7978.       Directory bottom bar menu.  On vertical menus (MENUBOXV) nHELPTEXT is
  7979.       displayed on the bottom screen line as each item is hilighted, as
  7980.       demonstrated in the SCRDEMO.SCR main menu.
  7981.  
  7982.      ERRORLEVEL
  7983.  
  7984.       None.  If nMENUITEM is invalid the script aborts and the error is
  7985.       pointed out to you.
  7986.  
  7987.      SEE ALSO
  7988.  
  7989.  
  7990.  
  7991.  
  7992.      Intellicomm v2.01               SCRIPT.DOC                            124
  7993.      
  7994.      
  7995.  
  7996.       MENUDEFINE, MENUITEMSTAT
  7997.  
  7998.      EXAMPLE
  7999.  
  8000.       menudefine "Item ~1" "Item ~2" "Item ~3"
  8001.       MENUHLP 1 "Item 1 description"
  8002.       MENUHLP 2 "Item 2 description"
  8003.       MENUHLP 3 "Item 3 description"
  8004.       menubar
  8005.  
  8006.      MENUITEMSTAT_____________________________________________________________
  8007.  
  8008.      SUMMARY
  8009.  
  8010.       MENUITEMSTAT nMENUITEM nSTATUS
  8011.  
  8012.      DESCRIPTION
  8013.  
  8014.       Sets or clears the disabled and/or hidden status of menu item nMENUITEM. 
  8015.       MENUDEFINE must be used before MENUITEMSTAT.
  8016.  
  8017.       Values for nSTATUS:
  8018.  
  8019.       0  Clear hidden/disabled status of nMENUITEM
  8020.       1  Disable nMENUITEM
  8021.       2  Hide nMENUITEM
  8022.  
  8023.      ERRORLEVEL
  8024.  
  8025.       None.  If nMENUITEM is invalid the script aborts and the error is
  8026.       pointed out to you.
  8027.  
  8028.      SEE ALSO
  8029.  
  8030.       MENUDEFINE, MENUHLP
  8031.  
  8032.      EXAMPLE
  8033.  
  8034.       menudefine "Item ~1" "~Unhide Item 3" "Item ~3"
  8035.       MENUITEMSTAT 3 2       ;Hide item 3
  8036.  
  8037.      again:
  8038.       menubar
  8039.  
  8040.       if $menuselection = 2  ;'Unhide Item 3' selected?
  8041.        MENUITEMSTAT 3 0      ;Unhide item 3
  8042.        goto again            ; and redisplay the menu
  8043.       endif
  8044.  
  8045.      MKDIR____________________________________________________________________
  8046.  
  8047.      SUMMARY
  8048.  
  8049.       MKDIR sPATH
  8050.  
  8051.  
  8052.  
  8053.  
  8054.      Intellicomm v2.01               SCRIPT.DOC                            125
  8055.      
  8056.      
  8057.  
  8058.      DESCRIPTION
  8059.  
  8060.       Creates the directory(s) specified by sPATH (same as MKDIR from DOS). 
  8061.       You can make multiple directories with a single call to MKDIR.  For
  8062.       example, if the directory \TEST doesn't exist, the following will make
  8063.       both \TEST and \TEST\TEST1 directories:
  8064.  
  8065.       MKDIR "\TEST\TEST1"
  8066.  
  8067.      ERRORLEVEL
  8068.  
  8069.       0  sPATH was created.
  8070.       1  sPATH couldn't be created (invalid drive or path, or root directory
  8071.          full).
  8072.       4  Permission denied (directory already exists).
  8073.       5  Miscellaneous errors.  The directory wasn't created.
  8074.  
  8075.      SEE ALSO
  8076.  
  8077.       RMDIR
  8078.  
  8079.      EXAMPLE
  8080.  
  8081.       MKDIR "$TEMP$"  ;create a temporary directory in the current directory
  8082.  
  8083.      MSGOPEN__________________________________________________________________
  8084.  
  8085.      SUMMARY
  8086.  
  8087.       MSGOPEN sMESSAGE ...
  8088.  
  8089.      DESCRIPTION
  8090.  
  8091.       Displays sMESSAGE in a centered message box.  Call MSGCLOSE to remove
  8092.       the message box.
  8093.  
  8094.      SEE ALSO
  8095.  
  8096.       MSGCLOSE, MSGWIND
  8097.  
  8098.      EXAMPLE
  8099.  
  8100.       variable k
  8101.       MSGOPEN "Please press a key..."
  8102.       inkeyw k
  8103.       msgclose
  8104.  
  8105.      MSGCLOSE_________________________________________________________________
  8106.  
  8107.      SUMMARY
  8108.  
  8109.       MSGCLOSE
  8110.  
  8111.      DESCRIPTION
  8112.  
  8113.  
  8114.  
  8115.  
  8116.      Intellicomm v2.01               SCRIPT.DOC                            126
  8117.      
  8118.      
  8119.  
  8120.       Closes a message window opened with MSGOPEN (restores the previous
  8121.       screen contents).
  8122.  
  8123.      SEE ALSO
  8124.  
  8125.       MSGOPEN, MSGWIND
  8126.  
  8127.      EXAMPLE
  8128.  
  8129.       variable k
  8130.       msgopen "Searching for SCRTUTOR.DOC..."
  8131.       diskfind "SCRTUTOR.DOC"
  8132.       MSGCLOSE
  8133.  
  8134.      MSGWIND__________________________________________________________________
  8135.  
  8136.      SUMMARY
  8137.  
  8138.       MSGWIND sMESSAGE ...
  8139.  
  8140.      DESCRIPTION
  8141.  
  8142.       Displays sMESSAGE in a centered box on screen, pauses for *sdelay TENTHS
  8143.       of a second, then closes the message box.  Use MSGWIND for status
  8144.       messages such as "Finished!", where it isn't imperative that the user
  8145.       see the message.
  8146.  
  8147.      SEE ALSO
  8148.  
  8149.       MSGOPEN, MSGCLOSE
  8150.  
  8151.      EXAMPLE
  8152.  
  8153.       MSGWIND "It is now: " $TIME   ;display the current time
  8154.  
  8155.      MUL______________________________________________________________________
  8156.  
  8157.      SUMMARY
  8158.  
  8159.       MUL vPRODUCT nMULTIPLICAND nMULTIPLIER
  8160.  
  8161.      DESCRIPTION
  8162.  
  8163.       Multiplies nMULTIPLICAND by nMULTIPLIER and stores the result in
  8164.       vPRODUCT.  As with any multiplication, the order of the multiplicand and
  8165.       multiplier is irrelevant:  7 x 4 = 28, as 4 x 7 = 28.
  8166.  
  8167.      SEE ALSO
  8168.  
  8169.       ADD, DIV, SUB
  8170.  
  8171.      EXAMPLE
  8172.  
  8173.       variable result
  8174.  
  8175.  
  8176.  
  8177.  
  8178.      Intellicomm v2.01               SCRIPT.DOC                            127
  8179.      
  8180.      
  8181.  
  8182.       MUL result 10 5   ;stores 10 x 5 (50) in variable 'result'
  8183.       print result
  8184.  
  8185.      NEWAREA__________________________________________________________________
  8186.  
  8187.      SUMMARY
  8188.  
  8189.       NEWAREA sAREA
  8190.  
  8191.      DESCRIPTION
  8192.  
  8193.       NEWAREA is a powerful command that can literally save you hours of
  8194.       script writing.  It uses the currently loaded BIF data to reliably
  8195.       access the BBS 'Main Menu', 'Message Menu', 'Bank Menu', or 'File Menu'
  8196.       to/from any other menu.  I.e. if you're in the File Menu and want to get
  8197.       to the Bank Menu, you needn't worry about how to exit the file menu nor
  8198.       how to access the Bank Menu, nor worry about which BBS prompts to handle
  8199.       for either task.  Icom uses the BIF information to handle the whole shot
  8200.       with a single call to NEWAREA.  You can also change BBS message/file
  8201.       areas with NEWAREA, again without worrying about how to go about it. 
  8202.       Icom uses the BIF data to make the change, and handles all the BBS
  8203.       prompts on the way.  It also makes use of Icom's error-handling routines
  8204.       (timeouts/BIF General menu exits, and it will re-try up to three times
  8205.       total if the initial area change fails).
  8206.  
  8207.       NEWAREA determines a change area request according to the sAREA
  8208.       parameter.  If sAREA is 'L', 'M', 'F', or 'B' enclosed in square
  8209.       brackets NEWAREA accesses the following BBS menu:
  8210.        
  8211.        [L]  The Logon Menu (the Main Menu A, Main Menu B prompts defined on
  8212.             BIF Logon screen).
  8213.        [M]  The 'Message Menu' defined on the BIF Message screen.  To access
  8214.             this menu, the BIF 'Access Msg. Menu' command will be sent, to
  8215.             leave it (if NEWAREA is at the Message Menu and you perform for
  8216.             example a NEWAREA [B]) the 'Leave Msg Menu' command is used. 
  8217.             NOTE: You needn't check the BIF to see whether an 'Access Msg.
  8218.             Menu' command is defined: if nothing is defined, Message functions
  8219.             can be carried out from the BBS [L]ogon (Main) Menu, and that is
  8220.             the menu NEWAREA will change to, if necessary.
  8221.        [F]  The 'File Menu' defined on the BIF Message screen.  To access this
  8222.             menu, the BIF 'Access File Menu' command will be sent, to leave it
  8223.             (if NEWAREA is at the File Menu and you perform for example a
  8224.             NEWAREA [B]) the 'Leave File Menu' command is used.
  8225.        [B]  The 'Bank Menu' defined on the BIF Message screen.  To access this
  8226.             menu, the BIF 'Access Bank Menu' command will be sent, to leave it
  8227.             (if NEWAREA is at the Bank Menu and you perform for example a
  8228.             NEWAREA [M]) the 'Leave Bank Menu' command is used.
  8229.  
  8230.       If you specify anything OTHER than a single letter enclosed in square
  8231.       brackets, NEWAREA assumes a message/file area change and will issue the
  8232.       "Area Change" command defined on the BIF File screen.
  8233.  
  8234.       NEWAREA keeps track of the current area and will not send redundant
  8235.       commands to access a menu/file area if you're already there.  Thus you
  8236.  
  8237.  
  8238.  
  8239.  
  8240.      Intellicomm v2.01               SCRIPT.DOC                            128
  8241.      
  8242.      
  8243.  
  8244.       can place calls to NEWAREA virtually anywhere in your script, just to
  8245.       make sure you're where you want to be.  If you're already there, NEWAREA
  8246.       sends no commands.  If you're at a different location, NEWAREA makes the
  8247.       change.  Of course this logic relies on the fact that you haven't
  8248.       changed areas behind NEWAREA's back.  If you use NEWAREA, you should use
  8249.       *only* NEWAREA to change BBS areas.  If you use SEND "OPEN QMAIL4" to
  8250.       access the Qmail door (Message Menu) or SEND "J 2"' to [J]oin a new
  8251.       conference, NEWAREA won't know about it and may fail the next time you
  8252.       call it.
  8253.  
  8254.       If you run your script from an automated job, and if Icom was at a main
  8255.       menu when your script was started, NEWAREA will already know which area
  8256.       of the BBS it's at (Icom keeps track of the current BBS area during
  8257.       automated jobs).  If you run your Script from the Script Manager or from
  8258.       the DOS command line, NEWAREA will first send the BIF General Menu Exit
  8259.       command (a couple of Ctrl-K's and ENTER normally) to locate its position
  8260.       on the BBS before attempting to change areas.
  8261.  
  8262.       NOTE: In order to perform BBS area changes, Intellicomm uses the WHEN
  8263.       slots which scripts use to track BBS prompts.  Since the script WHEN
  8264.       data and Intellicomm's own tracking routines use same memory space, any
  8265.       previously defined WHEN data is lost.  All WHENs are cleared when
  8266.       NEWAREA finishes.  I.e. do NOT use the NEWAREA command during a
  8267.       WHEN/WAITFOR, unless you use a GOTO to jump to the NEWAREA command, and
  8268.       then use another GOTO to get back above the WHENs to re-define them when
  8269.       NEWAREA finishes:
  8270.  
  8271.       redefine_whens:
  8272.        WHEN "prompt1" send "response 1"
  8273.        WHEN "prompt2" goto change_areas
  8274.        WAITFOR "prompt3" 120
  8275.        return
  8276.  
  8277.       change_areas:
  8278.        NEWAREA "[M]"         ;change to the message menu... WHENs are lost
  8279.        goto redefine_whens   ;get back up to re-define the WHEN/WAITFOR
  8280.  
  8281.       Further, if you're experienced with WHEN and know that it needn't
  8282.       actually be called immediately prior to a WAITFOR (i.e. you can execute
  8283.       the WHENs anywhere... Icom stores the data in memory and makes use if it
  8284.       the next time it runs into a WAITFOR), you'll have to take this into
  8285.       consideration if you use the NEWAREA command.  This will NOT work:
  8286.  
  8287.       WHEN "prompt 1" send "response 1"
  8288.       WHEN "prompt 2" send "response 2"
  8289.  
  8290.        ;later in the script you usually 'can' call WAITFOR and the WHENs
  8291.        ; would still be stored in memory.  But... if you use NEWAREA:
  8292.  
  8293.       NEWAREA "[L]"  ;Access the [L]ogon Menu (BBS Main menu)
  8294.  
  8295.        ;the WHENs defined above are now gone
  8296.  
  8297.       send "some command"
  8298.  
  8299.  
  8300.  
  8301.  
  8302.      Intellicomm v2.01               SCRIPT.DOC                            129
  8303.      
  8304.      
  8305.  
  8306.       WAITFOR "some menu" 120  ;simply waits... no WHENs are active
  8307.  
  8308.      ERRORLEVEL
  8309.  
  8310.       0  Area change successful.
  8311.       1  Area change unsuccessful (3 attempts failed, the connection was lost,
  8312.          etc).
  8313.       2  No BIF loaded.  You must call your script from an automated job (in
  8314.          which case the proper BIF data will already be loaded) or must use
  8315.          the LOADBIF or DIAL command to load a BIF into memory.
  8316.  
  8317.      SEE ALSO
  8318.  
  8319.       $BBS_AREA
  8320.  
  8321.      EXAMPLE
  8322.  
  8323.       NEWAREA "2"  ;Access conference 2; Sends J 2 Q on PCBoard systems
  8324.       if $ERRORLEVEL <> 0 return
  8325.       
  8326.       NEWAREA [M]  ;Access the Message Menu
  8327.       if $ERRORLEVEL <> 0 return
  8328.  
  8329.      NOTEXIST_________________________________________________________________
  8330.  
  8331.      SUMMARY
  8332.  
  8333.       NOTEXIST sFILESPEC cCOMMAND
  8334.  
  8335.      DESCRIPTION
  8336.  
  8337.       If sFILESPEC does NOT exist, cCOMMAND is executed.  If sFILESPEC does
  8338.       exist, cCOMMAND is skipped.
  8339.  
  8340.       sFILESPEC is a file specification (wildcards * and ? are accepted)
  8341.       including an optional drive and path (D:\PATH\*.BAT for example).  If
  8342.       you omit the drive (D:) the current drive ($CURDRIVE) is assumed.  If
  8343.       both the drive and path are omitted, the current path is assumed
  8344.       ($CURDIR).
  8345.  
  8346.      ERRORLEVEL
  8347.  
  8348.       No errorlevel is necessary.  Use cCOMMAND.
  8349.  
  8350.      SEE ALSO
  8351.  
  8352.       DISKFIND, EXIST, FINDFIRST, FINDNEXT
  8353.  
  8354.      EXAMPLE
  8355.  
  8356.       variable filename $HOME_DIR "POSTDOWN.BAT"
  8357.       exist filename edit filename  ;edit POSTDOWN.BAT if it exists
  8358.  
  8359.      OFFLINE__________________________________________________________________
  8360.  
  8361.  
  8362.  
  8363.  
  8364.      Intellicomm v2.01               SCRIPT.DOC                            130
  8365.      
  8366.      
  8367.  
  8368.      SUMMARY
  8369.  
  8370.       OFFLINE cCOMMAND
  8371.  
  8372.      DESCRIPTION
  8373.  
  8374.       If the modem is offline (not connected) cCOMMAND is executed.  If the
  8375.       modem is online (connected) cCOMMAND is skipped.
  8376.  
  8377.      SEE ALSO
  8378.  
  8379.       ONLINE, $CARRIER
  8380.  
  8381.      EXAMPLE
  8382.  
  8383.       OFFLINE exit   ;exit the script if modem is not online
  8384.  
  8385.      ONLINE___________________________________________________________________
  8386.  
  8387.      SUMMARY
  8388.  
  8389.       ONLINE cCOMMAND
  8390.  
  8391.      DESCRIPTION
  8392.  
  8393.       If the modem is online (connected) cCOMMAND is executed.  If the modem
  8394.       is offline (not connected) cCOMMAND is skipped.
  8395.  
  8396.      SEE ALSO
  8397.  
  8398.       ONLINE, $CARRIER
  8399.  
  8400.      EXAMPLE
  8401.  
  8402.       ONLINE exit   ;exit the script if modem is online
  8403.  
  8404.      OR_______________________________________________________________________
  8405.  
  8406.      SUMMARY
  8407.  
  8408.       OR vRESULT nNUM nBITMASK
  8409.  
  8410.      DESCRIPTION
  8411.  
  8412.       Performs a bitwise OR on nNUM using nBITMASK, and stores the result in
  8413.       vRESULT.  Unless you're a programmer, you probably will never find a use
  8414.       for OR.
  8415.  
  8416.      SEE ALSO
  8417.  
  8418.       AND, SHL, SHR, XOR
  8419.  
  8420.      EXAMPLE
  8421.  
  8422.  
  8423.  
  8424.  
  8425.      Intellicomm v2.01               SCRIPT.DOC                            131
  8426.      
  8427.      
  8428.  
  8429.       variable someflag 0
  8430.       OR someflag someflag 1  ;set bit 1 in variable 'someflag'
  8431.  
  8432.      PAUSE____________________________________________________________________
  8433.  
  8434.      SUMMARY
  8435.  
  8436.       PAUSE [MESSAGE] ...
  8437.  
  8438.      DESCRIPTION
  8439.  
  8440.       PAUSE displays an optional message to the user (if specified), then
  8441.       pauses script execution until the user presses a key.  If MESSAGE is
  8442.       specified it is printed at the current cursor position ($SCRN_X,
  8443.       $SCRN_Y) in the current screen color ($SCRN_COLOR).  The cursor (if on)
  8444.       will be displayed immediately following the message until the user
  8445.       presses a key.  Once a key is pressed, and if a MESSAGE was displayed,
  8446.       PAUSE prints "^M^J" (Carriage Return/Line Feed) to the screen to advance
  8447.       the cursor to the next screen line (terminating the line that MESSAGE
  8448.       was on).  And the script continues executing at the next script line (if
  8449.       any).
  8450.  
  8451.       Please also see the notes in the PRINT summary below.
  8452.  
  8453.      SEE ALSO
  8454.  
  8455.       BOXGETS, GETS, INKEY, INKEYW, INKEYT, PRINT, PRINTNC, PRINTRAW, WINDOW,
  8456.       WNDOPEN
  8457.  
  8458.      EXAMPLE
  8459.  
  8460.      PAUSE "Press a key to continue: "
  8461.  
  8462.      PRINT____________________________________________________________________
  8463.  
  8464.      SUMMARY
  8465.  
  8466.       PRINT DATA ...
  8467.  
  8468.      DESCRIPTION
  8469.  
  8470.       Displays DATA (either a number, string, or variable) on the screen in
  8471.       the current $SCRN_COLOR, at the current cursor position ($SCRN_X,
  8472.       $SCRN_Y) and follows it with a Carriage Return/Line Feed to terminate
  8473.       the line.  If DATA is too long to be displayed in the current WINDOW, it
  8474.       is either wrapped to the next screen line, or truncated (cut) at the
  8475.       current $WND_RIGHT position, depending on the setting of $SCRN_WRAP (0 =
  8476.       truncate, 1 = wrap).
  8477.  
  8478.       NOTE 1: If the capture file is currently open (see CAPTURE), data you
  8479.       display with PAUSE, PRINT, and PRINTNC is also written to the capture
  8480.       file.  To display data on the screen without capturing it, either turn
  8481.       capture off temporarily (CAPPUSH, then CAPCLOSE or CAPPAUSE, then CAPPOP
  8482.       to restore) or use the PRINTRAW command.
  8483.  
  8484.  
  8485.  
  8486.  
  8487.      Intellicomm v2.01               SCRIPT.DOC                            132
  8488.      
  8489.      
  8490.  
  8491.       NOTE 2: There are several characters you cannot print to the screen with
  8492.       the PRINT command.  PAUSE, PRINT, and PRINTNC perform special functions
  8493.       on certain control characters, if present in the data being printed. 
  8494.       The table below lists all these characters: the ASCII code (number) is
  8495.       first, the characters used to signify the control character in a string
  8496.       comes second (PRINT "^M" prints CR), the control character name (ESC,
  8497.       CR, etc.) is third, and a description of the Function it performs if
  8498.       printed with PAUSE, PRINT, or PRINTNC is fourth:
  8499.  
  8500.       Num Char Name                     Function
  8501.       ------------------------------------------------------------------------
  8502.       -  2    ^B  STX  Toggles 'bold' text on/off.  PRINT always starts
  8503.                        printing text in the color that $SCRN_COLOR is set to. 
  8504.                        If ^B is encountered, $SCRN_COLOR is temporarily set to
  8505.                        $BOLD_COLOR.  When another ^B is encountered (or if the
  8506.                        end of the PRINT string is reached) the previous screen
  8507.                        color is reset.  Example:  PRINT "Normal ^BBold^B
  8508.                        Normal"
  8509.                     The word "Bold" above would be printed in $BOLD_COLOR due
  8510.                     to the ^B's surrounding it.  The rest of the string would
  8511.                     be printed in $SCRN_COLOR.
  8512.        5   ^E  ENQ  Sends the ENQuiry response to the BBS (if any; defined on
  8513.                     the main setup "Terminal" screen).  You'll never want to
  8514.                     do this... it's just mentioned because that's what'll
  8515.                     happen if you try to print this character.  PRINT sends
  8516.                     characters through the terminal display, and the terminal
  8517.                     display responds to ^E ENQuiry, if found.
  8518.        7   ^G  BEL  Same as using BEEP.  If you have something important to
  8519.                     PRINT to the user, you can beep to wake him/her up.
  8520.                     Example: PRINT "^GHey, wake up!"
  8521.                     Note that if $SOUND is equal to 0 (zero), ^G characters 
  8522.                     make no sound, whether used in PAUSE, PRINT, or PRINTNC,
  8523.                     or received from the COM port.
  8524.        9   ^I  HT   Horizontal Tab moves to the next tab column.  Tab columns
  8525.                     exist every five characters from the left of the current
  8526.                     WINDOW ($WND_LEFT).  You can line up columns of data (a
  8527.                     filename, date, size, etc) on these tab columns, by using
  8528.                     tabs (^I) in your PAUSE, PRINT, PRINTNC statements.
  8529.       10   ^J  LF   Line Feed moves the cursor down one row (top to bottom),
  8530.                     keeping it in the same screen column (left to right).  If
  8531.                     the cursor is at the bottom of the current WINDOW when ^J
  8532.                     is printed, the contents of the window scrolls up one
  8533.                     line.  Use both ^M^J (CR/LF) if you want to move the
  8534.                     cursor to the beginning of the new line.  Note that PRINT
  8535.                     and PAUSE (after the key is pressed) both automatically
  8536.                     add ^M^J to the end of the data they print.  PRINTNC does
  8537.                     not.
  8538.       12   ^L  FF   Form Feed is the same as CLS (clear current WINDOW, move
  8539.                     cursor to position 1,1).
  8540.       13   ^M  CR   Carriage Return moves the cursor to screen column 1
  8541.                     (leftmost column, according to the current WINDOW, if any)
  8542.                     maintaining the current screen row.  Follow ^M with ^J
  8543.                     (Line Feed) to move to the next line.
  8544.       24   ^X  CAN  CANcel is the beginning of the Zmodem auto-download
  8545.  
  8546.  
  8547.  
  8548.  
  8549.      Intellicomm v2.01               SCRIPT.DOC                            133
  8550.      
  8551.      
  8552.  
  8553.                     sequence.  If *zauto (Zmodem auto-downloads on/off, main
  8554.                     setup variable) is non-zero, ^X will be "eaten" by PAUSE,
  8555.                     PRINT, and PRINTNC.  If *zauto is set to zero, ^X is
  8556.                     printed to the screen.
  8557.       27   ^[  ESC  Signifies the beginning of an ANSI escape code.  This
  8558.                     character (and perhaps one or more characters following
  8559.                     it, depending upon what follows) is never displayed by
  8560.                     PAUSE, PRINT or PRINTNC.
  8561.  
  8562.       To print any of the above characters to the screen directly, instead of
  8563.       having the terminal act upon the character, use the PRINTRAW command
  8564.       which writes directly to the screen without going through the terminal
  8565.       display routines.
  8566.  
  8567.      SEE ALSO
  8568.  
  8569.       PAUSE, PRINTNC, PRINTRAW, WINDOW, WNDOPEN
  8570.  
  8571.      EXAMPLE
  8572.  
  8573.       variable myvariable
  8574.       assign myvariable "some information"
  8575.  
  8576.       PRINT "Here is " myvariable " to read."
  8577.  
  8578.       ;Displays "Here is some information to read." (without the quotes).
  8579.  
  8580.      PRINTNC__________________________________________________________________
  8581.  
  8582.      SUMMARY
  8583.  
  8584.       PRINTNC [sDATA] ...
  8585.  
  8586.      DESCRIPTION
  8587.  
  8588.       Performs the same function as PRINT (see above), but PRINTNC does not
  8589.       add a Carriage Return/Line feed after sDATA.  I.e. you can use several
  8590.       PRINTNC commands to print data on the same screen line (though you can
  8591.       also accomplish that by specifying multiple parameters after a PRINT
  8592.       statement).  Please read the PRINT summary above for special
  8593.       considerations.
  8594.  
  8595.      SEE ALSO
  8596.  
  8597.       PAUSE, PRINT, PRINTRAW, WINDOW, WNDOPEN
  8598.  
  8599.      EXAMPLE
  8600.  
  8601.       variable keypressed
  8602.  
  8603.       ;This performs basically the same function as PAUSE, but you can
  8604.       ; check the key to see what the user pressed (you might want to cancel
  8605.       ; something if ^[ (ESC) is pressed)
  8606.  
  8607.  
  8608.  
  8609.  
  8610.      Intellicomm v2.01               SCRIPT.DOC                            134
  8611.      
  8612.      
  8613.  
  8614.       PRINTNC "Please press a key: "
  8615.       inkeyw keypressed
  8616.       PRINT    ;prints only ^M^J (CR/LF) to terminate the PRINTNC line above.
  8617.  
  8618.      PRINTRAW_________________________________________________________________
  8619.  
  8620.      SUMMARY
  8621.  
  8622.       PRINTRAW nX nY nCOLOR DATA ...
  8623.  
  8624.      DESCRIPTION
  8625.  
  8626.       Displays DATA (one or more constant strings/numbers or variables) on the
  8627.       video display at screen row nX, column nY (1 1 being the top left screen
  8628.       corner), in color nCOLOR.  See COLOR CODES in the online help, or in the
  8629.       Appendix of this manual for information on creating your own colors. 
  8630.       Usually you'll use one of the Icom system colors ($SCRN_COLOR,
  8631.       $BOLD_COLOR, etc) as the nCOLOR parameter.
  8632.  
  8633.       Note that PRINTRAW does not observe the current screen WINDOW nor does
  8634.       it move the screen cursor.  This allows you to print data on the status
  8635.       line (if it's on ... see $STAT_ON), or outside the current WINDOW, to
  8636.       print data in a window border opened with WNDOPEN for example.
  8637.  
  8638.       Further, you can display any ASCII character with PRINTRAW.  Several
  8639.       control characters perform functions when printed with PAUSE, PRINT or
  8640.       PRINTNC, while PRINTRAW displays all characters in their "raw" format
  8641.       (hence the name of the command).
  8642.  
  8643.       PRINTRAW is also faster than PRINT/PRINTNC, since it needn't observe the
  8644.       current WINDOW, nor perform translations of control characters.
  8645.  
  8646.      SEE ALSO
  8647.  
  8648.       BOX, PRINT, PRINTNC, SCROLL
  8649.  
  8650.      EXAMPLE
  8651.  
  8652.       ;Open a window, top corner 1,5, bottom corner 80,20
  8653.       wndopen "Sample Window" 1 5 80 20
  8654.       print "This goes inside the window, and you can't get outside with"
  8655.       print "either PAUSE, PRINT or PRINTNC."
  8656.  
  8657.       PRINTRAW 63 5 $BORDER_COLOR " In the Border! "
  8658.  
  8659.       ;Displays " In the Border! " (no quotes) at positon 63,5.  Line 5 is the
  8660.       ; top screen border position, and position 63 prints it on the right
  8661.       ; corner.  You always have to work out your screen coordinates with
  8662.       ; PRINTRAW.  It's more work than using PRINT, but you can do more with 
  8663.       ; it.
  8664.  
  8665.      PORT_____________________________________________________________________
  8666.  
  8667.      SUMMARY
  8668.  
  8669.  
  8670.  
  8671.  
  8672.      Intellicomm v2.01               SCRIPT.DOC                            135
  8673.      
  8674.      
  8675.  
  8676.       PORT nCOMPORT
  8677.  
  8678.      DESCRIPTION
  8679.  
  8680.       Closes the current COM port (any characters received at that port after
  8681.       it's closed will be lost) and opens a new COM port number nCOMPORT. 
  8682.       nCOMPORT must be a number from 1 through 8 (for COM1 to COM8).  If you
  8683.       use anything above COM4, the proper port address(es) and IRQ information
  8684.       must first be set up on the Icom main setup "Comm Port Setup" screen. 
  8685.       By default, all ports above COM4 point to (open) COM1.
  8686.  
  8687.       If a 16550 UART is installed, PORT also enables the 16550 FIFO buffer
  8688.       (if the *16550fl main setup variable is non-zero), and sets its receive
  8689.       and transmit triggers to *16550rx, *16550tx.  If you don't understand
  8690.       this, it's not important (though the online help topic "Optimizing
  8691.       Intellicomm" will explain it, if you're interested).  If you do
  8692.       understand it, you'll see that you can use the PORT command to change
  8693.       the 16550 receive/transmit triggers from a script, if necessary.
  8694.  
  8695.      ERRORLEVEL
  8696.  
  8697.       0  Port successfully opened.
  8698.       1  No memory for transmit/receive buffers, or unable to initialize the
  8699.          port itself.  There's not much to a COM port... you have your base
  8700.          address in the computer's memory and the IRQ line the port uses to
  8701.          send an interrupt to the processor.  Both items are dictated by the
  8702.          COM port hardware itself (i.e. see the documentation for your multi
  8703.          I/O card, or your modem docs if an internal modem).  Both the base
  8704.          port address and IRQ line can be configured, for any port from 1-8,
  8705.          on the main setup "Comm Port Settings" screen ... so if a port can't
  8706.          be opened (assuming you don't see an "Insufficient memory" message on
  8707.          the screen, which you will if there is no memory for the buffers) you
  8708.          should be able to fix the problem in the main setup.
  8709.       2  Invalid port specified.  You didn't follow the PORT command with a
  8710.          number from 1 through 8.
  8711.  
  8712.      EXAMPLE
  8713.  
  8714.       PORT 4   ;Open COM4
  8715.       send "This goes out COM4 now."
  8716.  
  8717.      REDIAL___________________________________________________________________
  8718.  
  8719.      SUMMARY
  8720.  
  8721.       REDIAL
  8722.  
  8723.      DESCRIPTION
  8724.  
  8725.       REDIAL will only be needed when you tag and dial multiple BIFs with the
  8726.       DIAL command.  Once DIAL connects to a BBS, it untags that BIF.  REDIAL
  8727.       can then be used to dial the remaining tagged BIFs (until it sets
  8728.       $ERRORLEVEL to non-zero, in which case nothing was left to dial).
  8729.  
  8730.  
  8731.  
  8732.  
  8733.      Intellicomm v2.01               SCRIPT.DOC                            136
  8734.      
  8735.      
  8736.  
  8737.       NOTE: Using the DIAL or REDIAL command causes any previously defined
  8738.       WHEN commands (for tracking BBS prompts) to be lost.  The dialer uses
  8739.       WHEN itself to track the modem response codes, and when it exits all
  8740.       WHENs are cleared.
  8741.  
  8742.      ERRORLEVEL
  8743.  
  8744.       0  You are now connected to the BBS/BIF specified in the $BIF_NAME
  8745.          System Variable, and that BIF has been untagged.
  8746.       1  Nothing left to dial, or user aborted.
  8747.  
  8748.      SEE ALSO
  8749.  
  8750.       DIAL
  8751.  
  8752.      EXAMPLE
  8753.  
  8754.      ;REDIAL is an advanced command, and here follows an advanced example. 
  8755.      ; Using the framework below, you could perform a fair equivalent to
  8756.      ; an Icom internal job dialing/logon session.  If you're faint of heart,
  8757.      ; or new to Icom scripts, skip this example.
  8758.  
  8759.      dial "!" 0               ;Tag/Dial all BBS's with ! in the BIF
  8760.      description
  8761.  
  8762.      while $errorlevel = 0    ;false if not connected
  8763.  
  8764.        ;Perform the auto-logon using the BIF information.  This can log on
  8765.        ; anywhere... as long as the BIF [L]ogon section is set up.
  8766.  
  8767.       when                              ;clear previous WHENs
  8768.       when *[L]namp sendbif "L" "namc"  ;BIF variables, name prompt and
  8769.      command
  8770.       when *[L]pasp sendbif "L" "pasc"  ;Password prompt/response
  8771.       when *[L]lanp sendbif "L" "lanc"  ;Language prompt/response
  8772.       when *[L]ecnp sendbif "L" "ecnc"  ;Confirm prompt/response
  8773.       when *[L]grap sendbif "L" "grac"  ;Graphics
  8774.       when *[L]scap sendbif "L" "scac"  ;Scan messages
  8775.       when *[L]paup sendbif "L" "pauc"  ;Pause
  8776.       when *[L]morp sendbif "L" "morc"  ;More
  8777.       when *[E]exac sendbif "E" "exap"  ;External Extra A
  8778.       when *[E]exbc sendbif "E" "exbp"  ; B
  8779.       when *[E]excc sendbif "E" "excp"  ; C
  8780.       when *[E]exdc sendbif "E" "exdp"  ; D
  8781.       waitfor *[L]mnap 120              ;wait 2 minutes max. for BBS main menu
  8782.  
  8783.       if $errorlevel = 0      ;WAITFOR worked; we're at the BBS main menu
  8784.        switch $BIF_NAME       ; but which BBS did we connect to?
  8785.         case "SOMEBIF1"
  8786.          gosub SomeBIF1_Job
  8787.         endcase
  8788.         case "SOMEBIF2"
  8789.          gosub SomeBIF2_Job
  8790.         endcase
  8791.  
  8792.  
  8793.  
  8794.  
  8795.      Intellicomm v2.01               SCRIPT.DOC                            137
  8796.      
  8797.      
  8798.  
  8799.          ;etc., for all the BIF descriptions you placed ! in
  8800.        endswitch
  8801.        send *[L]lofc          ;send the logoff command
  8802.        waitfor *[L]lofp 5     ;wait 5 seconds for the Logged Off prompt
  8803.       else                    ;WAITFOR timed out
  8804.        print "^M^J^GUnable to logon ... hanging up."
  8805.       endif
  8806.       
  8807.       hangup  ;make sure we're disconnected before trying to dial again
  8808.       REDIAL  ;Here we are at REDIAL, finally.  $ERRORLEVEL will be checked
  8809.               ; at the top of the loop, and we'll exit the loop if no more
  8810.               ; BIFs are tagged (or the user aborts dialing).
  8811.      endwhile
  8812.  
  8813.      return   ;All BIFs are finished
  8814.  
  8815.      SomeBIF1_Job:
  8816.         ;carry out a mail run or the like 
  8817.       return
  8818.  
  8819.      SomeBIF2_Job:
  8820.         ;whatever needs doing on BBS #2
  8821.       return
  8822.  
  8823.      RELOADSCRIPT_____________________________________________________________
  8824.  
  8825.      SUMMARY
  8826.  
  8827.       RELOADSCRIPT
  8828.  
  8829.      DESCRIPTION
  8830.  
  8831.       Reloads the currently executing script from disk, and begins executing
  8832.       it at the beginning again.  This command will mainly be of use to script
  8833.       writers who distribute scripts to the general public.  It can be used to
  8834.       reload/restart a script after the user has defined some initial setup
  8835.       information.
  8836.  
  8837.      EXAMPLE
  8838.  
  8839.      This example below is similar to what the POSTFILE.SCR does before it has
  8840.      been configured properly.  It causes a script to pause and "Edit"/reload
  8841.      itself, until the user sets the script up and removes the setup routine.
  8842.  
  8843.      ;---
  8844.      ;Attention User: Once you plug the proper information into the variables
  8845.      ; below, please remove these comments right down to the RELOADSCRIPT
  8846.      ; command.
  8847.  
  8848.      print $SCRIPT_NAME " has not been configured yet!"
  8849.      pause "Press a key to Edit..."
  8850.      edit $FULL_SCRIPT_NAME
  8851.      RELOADSCRIPT
  8852.  
  8853.  
  8854.  
  8855.  
  8856.      Intellicomm v2.01               SCRIPT.DOC                            138
  8857.      
  8858.      
  8859.  
  8860.      variable someinfo "Default"
  8861.       ;your main setup variables (what the user sets up) go here...
  8862.  
  8863.       ;the main body of your script goes here...
  8864.  
  8865.      return
  8866.  
  8867.  
  8868.      RENAME___________________________________________________________________
  8869.  
  8870.      SUMMARY
  8871.  
  8872.       RENAME sSOURCENAME sTARGETNAME
  8873.  
  8874.      DESCRIPTION
  8875.  
  8876.       Renames or moves a file.  Wildcards (* and ?) are not permitted.
  8877.  
  8878.       sSOURCENAME may contain a drive and path.  If the drive is omitted, the
  8879.       current drive is assumed.  If the path is omitted, the current directory
  8880.       is assumed.
  8881.  
  8882.       If sTARGETNAME contains a filename (but no D:\PATH), the file
  8883.       sSOURCENAME is renamed to sTARGENAME.  If sTARGETNAME contains only a
  8884.       path (D:\PATH or \PATH, etc) sSOURCENAME is MOVED to the directory
  8885.       specified by sTARGETNAME.
  8886.  
  8887.      ERRORLEVEL
  8888.  
  8889.       0  sSOURCENAME successfully renamed/moved.
  8890.       1  Unable to move/rename sSOURCENAME (sTARGETNAME is invalid).
  8891.       2  sSOURCENAME not found.
  8892.  
  8893.      EXAMPLE
  8894.  
  8895.       variable fname $HOME_DIR "EXCLUDE.KWD"  ;Exclude Files keyword list
  8896.  
  8897.       RENAME fname "EXCLUDE.TMP"
  8898.       importnew
  8899.       assign fname $HOME_DIR "EXCLUDE.TMP"
  8900.       RENAME fname "EXCLUDE.KWD"
  8901.  
  8902.      RENUMBER_________________________________________________________________
  8903.  
  8904.      SUMMARY
  8905.  
  8906.       RENUMBER sFILENAME nNUMTOTAL
  8907.  
  8908.      DESCRIPTION
  8909.  
  8910.       Renumbers the file sFILENAME to a maximum number of backup files
  8911.       specified by nNUMTOTAL.  RENUMBER renames files very quickly, placing
  8912.       numbers in either file filename or extension (and backup files) of
  8913.       sFILENAME.  Icom uses RENUMBER to rename the ICOM.CAP (capture) file
  8914.  
  8915.  
  8916.  
  8917.  
  8918.      Intellicomm v2.01               SCRIPT.DOC                            139
  8919.      
  8920.      
  8921.  
  8922.       just prior to dialing.
  8923.  
  8924.       sFILENAME can (and should) specify the full D:\PATH\FILENAME.EXT of the
  8925.       mail file you want to renumber.  Wildcards (* and ?) are not permitted. 
  8926.       If you specify wildcards in sFILENAME you may get a mess.
  8927.  
  8928.       nNUMTOTAL specifies the total number of backups of sFILENAME to keep on
  8929.       disk.
  8930.  
  8931.      ERRORLEVEL
  8932.  
  8933.       0  RENUMBER successful.
  8934.       1  sFILENAME not found.
  8935.  
  8936.      EXAMPLE
  8937.  
  8938.        ;Renumber the capture files...
  8939.       cappush
  8940.       capclose
  8941.       renumber $CAP_NAME *capnum
  8942.       cappop
  8943.  
  8944.      RETURN___________________________________________________________________
  8945.  
  8946.      SUMMARY
  8947.  
  8948.       RETURN [nERRORCODE]
  8949.  
  8950.      DESCRIPTION
  8951.  
  8952.       RETURN pulls double-duty and serves two purposes in the script language. 
  8953.       When Icom encounters a RETURN it first checks to see whether you
  8954.       previously executed a GOSUB (Goto Subroutine) command, and if so it
  8955.       simply returns to the line following the GOSUB.  However, if RETURN is
  8956.       found and no GOSUB has been executed, Icom ends the current script at
  8957.       that point (RETURNs to the calling script, or back to the automated job,
  8958.       or Script Manager, or wherever the script was called from).  The
  8959.       optional nERRORCODE is only checked in the latter case, when RETURN is
  8960.       used to exit a script.  Further, nERRORCODE is only of use when your
  8961.       script is called during an automated job, via a job Custom Command or
  8962.       BIF command.  In most cases, no nERRORCODE number will be specified at
  8963.       all, and you'll simply use RETURN alone.  There are a number of factors
  8964.       that determine what Icom does when a RETURN is found, and what it does
  8965.       if you specify an 'errorcode'.  All the details are given in
  8966.       SCRTUTOR.DOC in the section "WHAT HAPPENS WHEN A SCRIPT ENDS?".
  8967.  
  8968.      SEE ALSO
  8969.  
  8970.       GOSUB, SYSTEM
  8971.  
  8972.      EXAMPLE
  8973.  
  8974.       offline goto done    ;if not online, goto done
  8975.       ...                  ;main body of script here
  8976.  
  8977.  
  8978.  
  8979.  
  8980.      Intellicomm v2.01               SCRIPT.DOC                            140
  8981.      
  8982.      
  8983.  
  8984.      done:
  8985.       return               ;exit the script
  8986.  
  8987.      RMDIR____________________________________________________________________
  8988.  
  8989.      SUMMARY
  8990.  
  8991.       RMDIR sDIRECTORY ...
  8992.  
  8993.      DESCRIPTION
  8994.  
  8995.       Removes the directory sDIRECTORY.  The directory must be empty
  8996.       (including sub-subdirectories) for RMDIR to succeed.
  8997.  
  8998.       Note that the ... above doesn't mean that you can specify multiple
  8999.       directories to remove.  Like all script parameters, ... simply signifies
  9000.       that you can build the last parameter (sDIRECTORY is the last parameter
  9001.       in this case) like this:
  9002.  
  9003.        RMDIR "C:" somevariable anothervariable ... etc.
  9004.  
  9005.       All parameters specified are joined together to make a single parameter.
  9006.  
  9007.      ERRORLEVEL
  9008.  
  9009.       0  sDIRECTORY was removed.
  9010.       1  sDIRECTORY couldn't be removed (invalid drive or path).
  9011.       4  Permission denied (directory not empty).
  9012.       5  Miscellaneous errors.  The directory wasn't removed.
  9013.  
  9014.      SEE ALSO
  9015.  
  9016.       MKDIR
  9017.  
  9018.      EXAMPLE
  9019.  
  9020.       variable tmpdir "\$TEMP$.$$$"
  9021.  
  9022.       mkdir tmpdir   ;make a temporary directory off the root directory
  9023.       ...            ;do your stuff in the temp directory
  9024.       delete tmpdir "\*.*"  ;kill any files you created/copied, etc
  9025.                             ; (expands to \$TEMP$.$$$\*.*)
  9026.       RMDIR tmpdir
  9027.  
  9028.      RXFLUSH__________________________________________________________________
  9029.  
  9030.      SUMMARY
  9031.  
  9032.       RXFLUSH
  9033.  
  9034.      DESCRIPTION
  9035.  
  9036.       'Flushes' or clears the Receive Buffer (a holding area for characters
  9037.       received from the COM port, that have not been displayed to the screen
  9038.  
  9039.  
  9040.  
  9041.  
  9042.      Intellicomm v2.01               SCRIPT.DOC                            141
  9043.      
  9044.      
  9045.  
  9046.       yet).  Use to get rid of line noise, logoff bulletins, etc.
  9047.  
  9048.      SEE ALSO
  9049.  
  9050.       TXFLUSH
  9051.  
  9052.      SAVEBIF__________________________________________________________________
  9053.  
  9054.      SUMMARY
  9055.  
  9056.       SAVEBIF [sBIF_NAME]
  9057.  
  9058.      DESCRIPTION
  9059.  
  9060.       This advanced script command saves the currently loaded BIF information
  9061.       to disk.  If sBIF_NAME is omitted, $BIF_NAME (the current BIF filename)
  9062.       is assumed.
  9063.  
  9064.       Only a filename (JOESBBS, SOMEBIF, etc) is required if sBIF_NAME is
  9065.       specified.  You may specify a D:\PATH and extension if necessary (i.e.
  9066.       if you used FINDFIRST/FINDNEXT to locate various BIF filenames) but
  9067.       SAVEBIF always always saves in $BIF_DIR (ASSIGN $BIF_DIR another value
  9068.       to save to another directory) using the extension .BIF.
  9069.  
  9070.       NOTE 1: Don't use SAVEBIF unless you fully understand the LOADBIF
  9071.       command and BIF Variables.  SAVEBIF is meant to be used after you modify
  9072.       one or more BIF Variables, and you wish to save the modified information
  9073.       to disk.
  9074.  
  9075.       NOTE 2: If sBIF_NAME is specified and a BIF already exists using the
  9076.       same filename, the existing .BIF will be overwritten.  You can use the
  9077.       EXIST or FINDFIRST command to see if a given BIFID already exists:
  9078.  
  9079.        variable bifname "SOME_ID"
  9080.        variable temp
  9081.  
  9082.        assign temp $BIF_DIR bifname
  9083.        notexist temp SAVEBIF bifname
  9084.  
  9085.      ERRORLEVEL
  9086.  
  9087.       0  SAVEBIF successful.
  9088.       1  SAVEBIF unsuccessful (disk write error, invalid sBIF_NAME, disk
  9089.      full).
  9090.  
  9091.      SEE ALSO
  9092.  
  9093.       LOADBIF
  9094.  
  9095.      EXAMPLE
  9096.  
  9097.        ;Could be used to automatically change the Logon Name (or anything
  9098.        ; else) in all BIFs.
  9099.  
  9100.  
  9101.  
  9102.  
  9103.      Intellicomm v2.01               SCRIPT.DOC                            142
  9104.      
  9105.      
  9106.  
  9107.       variable bifname $BIF_DIR "*.BIF"
  9108.       variable v
  9109.  
  9110.       findfirst bifname bifname  ;store the first BIF in 'bifname'
  9111.  
  9112.       while $errorlevel = 0
  9113.        substr v *[L]desc 0 1     ;get the 1st character of the BBS/Host Name
  9114.        if v <> "["               ;don't mess with BIF templates...
  9115.         loadbif bifname
  9116.         assign *[L]namc "Joe Smith"
  9117.         SAVEBIF
  9118.        endif
  9119.        findnext bifname
  9120.       endwhile
  9121.  
  9122.      SAVEINI__________________________________________________________________
  9123.  
  9124.      SUMMARY
  9125.  
  9126.       SAVEINI [sINI_NAME]
  9127.  
  9128.      DESCRIPTION
  9129.  
  9130.       This advanced script command saves the currently loaded INI (main setup
  9131.       variables) information to disk.  If sINI_NAME is omitted, $INI_NAME (the
  9132.       current main setup file) is assumed.
  9133.  
  9134.       Only a filename (CUSTOM, SOMEINI, etc) is required if sINI_NAME is
  9135.       specified.  You may specify a D:\PATH and extension if necessary (i.e.
  9136.       if you used FINDFIRST/FINDNEXT to locate various INI filenames) but
  9137.       SAVEINI always always saves in $HOME_DIR (which cannot be modified)
  9138.       using the extension .INI.
  9139.  
  9140.       NOTE 1: Don't use SAVEINI unless you fully understand the LOADINI
  9141.       command and Main Setup Variables.  SAVEINI is meant to be used after you
  9142.       modify one or more Main Setup Variables, and you wish to save the
  9143.       modified information to disk.
  9144.  
  9145.       NOTE 2: If sINI_NAME is specified and an INI already exists using the
  9146.       same filename, the existing .INI will be overwritten!  You can use the
  9147.       EXIST or FINDFIRST command to see if a given .INI file already exists:
  9148.  
  9149.        variable ininame "CUSTOM"
  9150.        variable temp
  9151.  
  9152.        assign temp $HOME_DIR ininame
  9153.        notexist temp SAVEINI ininame
  9154.  
  9155.      ERRORLEVEL
  9156.  
  9157.       0  SAVEINI successful.
  9158.       1  SAVEINI unsuccessful (disk write error, invalid sINI_NAME, disk
  9159.      full).
  9160.  
  9161.  
  9162.  
  9163.  
  9164.      Intellicomm v2.01               SCRIPT.DOC                            143
  9165.      
  9166.      
  9167.  
  9168.      SEE ALSO
  9169.  
  9170.       LOADINI
  9171.  
  9172.      EXAMPLE
  9173.  
  9174.        ;Could be used to automatically change information in all .INI
  9175.        ; files.  This example changes your home telephone number (User
  9176.        ; Settings screen).
  9177.  
  9178.       variable ini_name $HOME_DIR "*.INI"
  9179.       variable v
  9180.  
  9181.       findfirst ini_name ini_name  ;store the first Ini in 'ini_name'
  9182.  
  9183.       while $errorlevel = 0
  9184.        loadini ini_name
  9185.        assign *uhphn "555-555-1234"
  9186.        SAVEINI ini_name
  9187.        findnext ini_name
  9188.       endwhile
  9189.  
  9190.      SCAPTURE_________________________________________________________________
  9191.  
  9192.      SUMMARY
  9193.  
  9194.       SCAPTURE [sFILENAME] ...
  9195.  
  9196.      DESCRIPTION
  9197.  
  9198.       Saves the contents of the screen to the file sFILENAME.  If sFILENAME is
  9199.       omitted, the default Screen Capture Filename (*scap; defined on the main
  9200.       setup Filenames and Path screen) is assumed.  If sFILENAME is specified
  9201.       but no D:\PATH is given, the file is saved in the current directory.
  9202.  
  9203.       NOTE: SCAPTURE always adds to the end of files.  It never overwrites
  9204.       files.  If you want to overwrite, simply DELETE the existing file (if
  9205.       any) before you use SCAPTURE.
  9206.  
  9207.      SEE ALSO
  9208.  
  9209.       CAPTURE
  9210.  
  9211.      EXAMPLE
  9212.  
  9213.       send "some command"
  9214.       waitfor "some text"
  9215.       SCAPTURE
  9216.       send "^MG"
  9217.       hangup
  9218.       list *scap   ;display the screen capture file
  9219.  
  9220.      SCREENBLANK______________________________________________________________
  9221.      SCREENRESTORE____________________________________________________________
  9222.  
  9223.  
  9224.  
  9225.  
  9226.      Intellicomm v2.01               SCRIPT.DOC                            144
  9227.      
  9228.      
  9229.  
  9230.      SUMMARY
  9231.  
  9232.       SCREENBLANK
  9233.       SCREENRESTORE
  9234.  
  9235.      DESCRIPTION
  9236.  
  9237.       SCREENBLANK activates the screen blanker, just as if the usual
  9238.       inactivity period defined by the user had elapsed.  Note that if the
  9239.       user does not have the screen blanker enabled (Icom main setup,
  9240.       Screen/Color Settings), the SCREENBLANK command has no effect.  There
  9241.       usually will be no need to use the SCREENBLANK command, since
  9242.       Intellicomm activates the screen blanker on its own (after the user-
  9243.       defined inactivity period) even when scripts are running.  The exception
  9244.       to this is if you set $KEY_CHECK to 0 (zero) to do your own keystroke
  9245.       handling.  If that's the case it'll be up to you to blank the screen
  9246.       using SCREENBLANK.
  9247.  
  9248.       SCREENRESTORE restores the screen (if blanked) as if the user had
  9249.       pressed a key.  You should only use this command when you must get the
  9250.       user's attention for some reason (to print an error message or the
  9251.       like), and in most cases Intellicomm itself will automatically restore
  9252.       the screen when something 'new' happens.  For example, if you use
  9253.       WNDOPEN, MSGWIND, BOX ... or MENUBAR, MENUBOXH, MENUBOXV, or
  9254.       BOXGETS/GETS, or after a file transfer completes, or if Icom prints its
  9255.       own error window, SCREENRESTORE will be called automatically.  You'll
  9256.       only have to use it in rare cases.
  9257.  
  9258.      EXAMPLE
  9259.  
  9260.       variable old_key_check $KEY_CHECK  ;save previous value
  9261.       assign $KEY_CHECK 0                ;keys are no longer checked by Icom
  9262.  
  9263.       SCREENRESTORE                      ;make sure this is displayed
  9264.       cls
  9265.       print "NOTE: Do not attempt to abort this file transfer!"
  9266.       delay 50
  9267.  
  9268.        ;the user cannot abort the file transfer due to $KEY_CHECK 0 above
  9269.        ; and further, without doing key checking, Icom will not activate
  9270.        ; the screen blanker
  9271.  
  9272.       SCREENBLANK
  9273.       download "X" "IMPORTNT.FIL"
  9274.       ;SCREENRESTORE is called automatically after the transfer.  It wouldn't
  9275.       ; hurt anything to call it again here, but... it's not necessary.
  9276.  
  9277.       assign $KEY_CHECK old_key_check    ;restore previous value
  9278.  
  9279.      SCRIPT___________________________________________________________________
  9280.  
  9281.      SUMMARY
  9282.  
  9283.       SCRIPT sSCRIPTNAME sPARAMETER ...
  9284.  
  9285.  
  9286.  
  9287.  
  9288.      Intellicomm v2.01               SCRIPT.DOC                            145
  9289.      
  9290.      
  9291.  
  9292.      DESCRIPTION
  9293.  
  9294.       Runs another script from within a script, then continues running the
  9295.       previous script at the next line after the SCRIPT command.  sSCRIPTNAME
  9296.       is the name of the script to run.  Any parameters that follow the script
  9297.       name are placed in the GlobalStr array (see the 'Global Variables'
  9298.       section in SCRTUTOR.DOC) for use in the called script.
  9299.  
  9300.       If both sSCRIPTNAME and sPARAMETER are omitted, the Script Manager is
  9301.       displayed allowing the user to select one or more scripts to Run.
  9302.  
  9303.      ERRORLEVEL
  9304.  
  9305.       0  sSCRIPTNAME loaded and executed with no errors.
  9306.  
  9307.       Any other value in $ERRORLEVEL signifies an error loading the script or
  9308.       an error RETURN code from the called script.  See the RETURN command for
  9309.       more details.
  9310.  
  9311.      SEE ALSO
  9312.  
  9313.       EXIT, RETURN
  9314.  
  9315.      EXAMPLE
  9316.  
  9317.        ;Execute POSTFILE.SCR on the file C:\ICOM\GET\ICOM201A.ZIP"
  9318.       SCRIPT "POSTFILE.SCR" "ICOM201" ".ZIP" "C:\ICOM\GET\ICOM201A.ZIP"
  9319.  
  9320.      SCROLL___________________________________________________________________
  9321.  
  9322.      SUMMARY
  9323.  
  9324.       SCROLL nX1 nY1 nX2 nY2 nMODE nCOLOR
  9325.  
  9326.      DESCRIPTION
  9327.  
  9328.       Scrolls or clears an area of the screen.  nX1 nY1 specify the top
  9329.       corner, nX2, nY2 specify the bottom corner ('X' is a screen column
  9330.       number from left to right, 'Y' is a screen row number from top to
  9331.       bottom.  1 1 is the top corner of the screen, $SCRN_WIDTH, $SCRN_HEIGHT
  9332.       [normally 80, 25] is the bottom corner of the screen).  Screen windows
  9333.       set with the WINDOW or WNDOPEN command are ignored by SCROLL, meaning
  9334.       that 1 1 is always the same (the top corner of the screen), regardless
  9335.       of whether a WINDOW is set.
  9336.  
  9337.       nMODE tells SCROLL what to do.  Positive numbers tell it to scroll the
  9338.       text UP, negative numbers tell it to scroll the text DOWN, zero tells it
  9339.       to simply clear the area.
  9340.  
  9341.       nCOLOR is the screen color used to fill in the scrolled (or cleared)
  9342.       area.  For example if you scroll the screen up by one line, you'll then
  9343.       have a blank line where the bottom-most line used to be.  nCOLOR tells
  9344.       SCROLL what color to set that bottom-most line to.  Normally you'll use
  9345.       one of the $XXXX_COLOR System Variables such as $SCRN_COLOR, $TERM_COLOR
  9346.  
  9347.  
  9348.  
  9349.  
  9350.      Intellicomm v2.01               SCRIPT.DOC                            146
  9351.      
  9352.      
  9353.  
  9354.       or $NORM_COLOR.  Please see the COLOR CODES Appendix for custom colors.
  9355.  
  9356.      SEE ALSO
  9357.  
  9358.       CLS
  9359.  
  9360.      EXAMPLE
  9361.  
  9362.       variable line 1
  9363.  
  9364.       cls
  9365.       while line < $WND_BTM  ;$WND_BTM accounts for the status line, if on
  9366.        print "Line " line
  9367.       endwhile
  9368.       
  9369.       pause "Press a key to scroll..."
  9370.       SCROLL 1 1 $SCRN_WIDTH $WND_BTM 1 $SCRN_COLOR
  9371.  
  9372.      SCROLLBACK_______________________________________________________________
  9373.  
  9374.      SUMMARY
  9375.  
  9376.       SCROLLBACK
  9377.  
  9378.      DESCRIPTION
  9379.  
  9380.       Enters the Terminal's scrollback buffer (same as pressing [Alt-B] from
  9381.       Terminal Mode).  This command was included mainly for use by Script
  9382.       Learn mode, and you probably won't have much use for it in your own
  9383.       scripts unless you turn $KEY_CHECK off.  Normally you'll be better off
  9384.       letting Icom just process the hotkeys ([Alt-B], etc) itself.
  9385.  
  9386.      EXAMPLE
  9387.  
  9388.       See INKEY for an example of turning $KEY_CHECK off, and processing usual
  9389.       Icom hotkeys via script commands.
  9390.  
  9391.      SEND_____________________________________________________________________
  9392.      SENDNC___________________________________________________________________
  9393.      SENDNCP__________________________________________________________________
  9394.      SENDNP___________________________________________________________________
  9395.  
  9396.      SUMMARY
  9397.  
  9398.       SEND [sDATA ...]
  9399.       SENDNC sDATA ...
  9400.       SENDNCP sDATA ...
  9401.       SENDNP [sDATA ...]
  9402.  
  9403.      DESCRIPTION
  9404.  
  9405.       All send sDATA (one or more constant strings/numbers, or variables) out
  9406.       the current COM port ($COM_PORT).
  9407.  
  9408.  
  9409.  
  9410.  
  9411.      Intellicomm v2.01               SCRIPT.DOC                            147
  9412.      
  9413.      
  9414.  
  9415.       SEND and SENDNP add a Carriage Return (CR; same as pressing [Enter])
  9416.       after sSDATA; while SENDNC (NC for 'N'o 'C'R) and SENDNCP do not.
  9417.  
  9418.       Further, SEND and SENDNC delay the sending of sDATA for the duration of
  9419.       the "Response Delay" item defined in BIF screen 1, if the modem is
  9420.       connected and a BIF is in use.  The 'NP' variations SENDNCP and SENDNP
  9421.       (NP for 'N'o 'P'ause) do not.
  9422.  
  9423.       Control characters can be specified in sDATA in the usual manner, by
  9424.       preceding the character with a caret (^) (see SCRTUTOR.DOC and the ASCII
  9425.       CODES appendix).  Further, a tilde (~) causes a 1 second delay in the
  9426.       sending of sDATA; usually to slow the command down to let the BBS (or
  9427.       modem) catch up.
  9428.  
  9429.       As mentioned above, by default both SEND and SENDNP add a carriage
  9430.       return (CR) after sDATA, which is the same as pressing [Enter] on your
  9431.       keyboard. But you can control this by modifying the $SEND_CR System
  9432.       Variable.  On some BBS's, you don't want a CR to follow the command (if
  9433.       BBS "hotkeys" are in use), while on others you must enter the command
  9434.       with a CR.  Rather than re-writing your scripts and changing SEND to
  9435.       SENDNC (send with no CR) or vice versa, you can stick with SEND in all
  9436.       your scripts and control whether a CR is added or not by changing the
  9437.       $SEND_CR System Variable at the top of the script.  If $SEND_CR is non-
  9438.       zero, a CR is added by SEND/SENDNP.  If $SEND_CR is zero, no CR is
  9439.       added.
  9440.  
  9441.       $SEND_CR can also be handy in making your scripts more user-friendly. 
  9442.       You can tell SEND whether to add a CR or not by checking the BIF "CR
  9443.       w/Commands?" item on BIF screen 1:
  9444.  
  9445.        if *[G]adcr = "Yes"   ;Add CR?  [G] = BIF [G]eneral section (scrn 1)
  9446.         assign $SEND_CR 1    ;SEND/SENDNP add carriage returns
  9447.        else
  9448.         assign $SEND_CR 0    ;SEND/SENDNP don't add CR's
  9449.        endif
  9450.  
  9451.       With the above in place at the top of a script the user could simply
  9452.       modify the BIF to get the script to operate differently.
  9453.  
  9454.       NOTE: If you're dealing with BIF information (BIF variables) in your
  9455.       script; instead of using SEND to send BIF responses/commands, you should
  9456.       instead use SENDBIF, which interprets the special BIF command
  9457.       characters:
  9458.  
  9459.        @ = Run another script
  9460.        & = Execute a single script command
  9461.        ! = Execute a DOS command
  9462.  
  9463.      SEE ALSO
  9464.  
  9465.       $SEND_CR
  9466.  
  9467.      SEND EXAMPLE
  9468.  
  9469.  
  9470.  
  9471.  
  9472.      Intellicomm v2.01               SCRIPT.DOC                            148
  9473.      
  9474.      
  9475.  
  9476.       SEND "D^M~NICECAR.GIF^M~Z"
  9477.        
  9478.         ;Translation:
  9479.         ; [D]ownload   ([Enter] and a 1 second pause)
  9480.         ; NICECAR.GIF  ([Enter] and a 1 second pause)
  9481.         ; [Z]modem     ([Enter] added by SEND)
  9482.  
  9483.       delay 30
  9484.       download "Z"
  9485.  
  9486.      SENDNC EXAMPLE
  9487.  
  9488.       variable UserName
  9489.  
  9490.       SENDNC "Please enter your name: "
  9491.       cgets UserName 50 "^M" 60
  9492.  
  9493.       send "^M^JWelcome, " UserName "."
  9494.  
  9495.      SENDBIF__________________________________________________________________
  9496.  
  9497.      SUMMARY
  9498.  
  9499.       SENDBIF sSECTION sTAG
  9500.  
  9501.      DESCRIPTION
  9502.  
  9503.       SENDBIF is used to handle BIF responses, and it usually sends one or
  9504.       more commands to the BBS.  It calls the same routine that Intellicomm
  9505.       itself calls to handle BIF responses, when a BIF prompt is found.  I.e.
  9506.       you will only want to use it when you're certain a BIF has been properly
  9507.       set up.
  9508.  
  9509.       sSECTION is the BIF section, sTAG is the four letter tag of a specific
  9510.       item within a section.  The BIF Variables section outlines all BIF
  9511.       sections and tags.
  9512.  
  9513.       If you use SENDBIF in your scripts (as opposed to regular SEND), you'll
  9514.       be able to control what your scripts send, and how that data it sent,
  9515.       directly from the BIF, instead of having to modify your script directly.
  9516.  
  9517.       SENDBIF supports the following special characters:
  9518.  
  9519.        ^   A tilde is used to specify a control charater (^M is [Enter], ^[ is
  9520.            [Esc], etc.  See the ASCII CODES Appendix).
  9521.        ~   Causes a one second delay.
  9522.  
  9523.       Further, it supports the special command characters permitted in BIF
  9524.       responses:
  9525.  
  9526.        @SCRIPTNAME = Run another script
  9527.        &COMMAND    = Execute a single script command
  9528.        !COMMAND    = Execute a DOS command
  9529.  
  9530.  
  9531.  
  9532.  
  9533.      Intellicomm v2.01               SCRIPT.DOC                            149
  9534.      
  9535.      
  9536.  
  9537.       And both the Response Delay and BS Protection (BIF screen 1) are also
  9538.       supported by SENDBIF.  The Response Delay allows you to pause SENDBIF
  9539.       for a specified length of time (in tenths of a second) before sending
  9540.       the sDATA parameter, and this can be handy on BBS's that flush their
  9541.       input buffers after displaying prompts.  The BS Protection (Backspace
  9542.       Protection) item allows you to have SENDBIF send a specified number of
  9543.       Backspace characters to the BBS, after the Response Delay, to eliminate
  9544.       line noise before sending the proper response.
  9545.  
  9546.      SEE ALSO
  9547.  
  9548.       SEND
  9549.  
  9550.      EXAMPLE
  9551.  
  9552.       Please see the REDIAL example.
  9553.  
  9554.      SENDKEY__________________________________________________________________
  9555.  
  9556.      SUMMARY
  9557.  
  9558.       SENDKEY sKEY ...
  9559.  
  9560.      DESCRIPTION
  9561.  
  9562.       SENDKEY allows you to send one or more keystrokes to the Icom terminal
  9563.       key handler.  The key codes sent via SENDKEY look no different to
  9564.       Intellicomm than had you pressed the key(s) at the keyboard.  You may
  9565.       specify up to 128 keys all with one SENDKEY command.  The 'key'
  9566.       parameter(s) can be either a text string in quotes:
  9567.  
  9568.        SENDKEY "Send this"     ;puts nine keys into the key queue
  9569.  
  9570.       and/or an extended key code, as outlined in the KEY CODES Appendix:
  9571.  
  9572.        SENDKEY 7936            ;puts a single extended key code in the queue
  9573.  
  9574.       SENDKEY converts the keycode differently depending on whether the sKEY
  9575.       parameter is in quotes or not.  If you use this:
  9576.  
  9577.        SENDKEY "15104"       ;15104 is the keycode for the [F1] key
  9578.  
  9579.       it will NOT translate to extended keycode 15104.  Due to the quotes, it
  9580.       will be processed as five separate keystrokes: 1, 5, 1, 0, and 4.  If
  9581.       you use this:
  9582.  
  9583.        SENDKEY 15104         ;no quotes
  9584.  
  9585.       all five characters are converted to a single number (extended keycode
  9586.       15104; the [F1] key).  If you specify more than one 'key' parameter,
  9587.       each must be separated by at least one space or TAB character as with
  9588.       all script parameters.  
  9589.  
  9590.       If a sKEY parameter is an Icom terminal hotkey such as [F1] (help) [Alt-
  9591.  
  9592.  
  9593.  
  9594.  
  9595.      Intellicomm v2.01               SCRIPT.DOC                            150
  9596.      
  9597.      
  9598.  
  9599.       Z] (terminal menu), [Alt-D] (change to the BBS/Dialing Directory), etc.,
  9600.       then it pops up the appropriate Icom menu or carries out whatever task
  9601.       the hotkey would if you pressed the key from terminal mode.  This is
  9602.       where it can be useful to stack several key codes with a single SENDKEY
  9603.       command, since it allows you to operate WITHIN the menu after it opens
  9604.       (see the example below).  However, if 'doorway mode' is on, the extended
  9605.       keycode(s) are simply sent to the BBS (see the $DOORWAY System Variable)
  9606.       no differently than if you pressed the key with doorway mode on.  To
  9607.       send extended keycodes to the BBS instead of having Icom process it as a
  9608.       hotkey, simply turn doorway mode on:
  9609.  
  9610.        variable old_doorway $DOORWAY  ;save the old doorway mode status
  9611.  
  9612.        assign $DOORWAY 1              ;1 turns doorway mode on
  9613.        SENDKEY 15104                  ;send [F1] to the BBS instead of to Icom
  9614.        assign $DOORWAY old_doorway    ;reset doorway mode to its previous
  9615.      state
  9616.  
  9617.       Doorway Mode is used by many BBS doors for extended keycode handling
  9618.       (i.e. use of real menus with hilight bars which allow [Up], [Down] to
  9619.       move the bar, etc).  If you use a BBS door that supports Doorway Mode,
  9620.       you'll know what it is.  If you don't, then Doorway Mode and sending
  9621.       extended keycodes to the BBS with SENDKEY is of no use to you.
  9622.  
  9623.       With doorway mode OFF you can have Icom actually perform tasks within
  9624.       menus you pop up, by stringing several keys together (similar to
  9625.       macros).  However, SENDKEY has not been tested extensively for this use
  9626.       (it was included only for Script Learn mode, for oddball keycodes), so
  9627.       don't be surprised if you can't carry out an entire Intellicomm session
  9628.       with SENDKEY.  See the EXAMPLE below for details of a semi-long SENDKEY
  9629.       example that does work.
  9630.       
  9631.       sKEY parameters (as with all Icom script parameters) may also be
  9632.       variables.  If the contents of the variable contains only numbers, then
  9633.       it's the same as using a constant number (an extended keycode).  If the
  9634.       contents of the variable contains one or more non-numeric characters,
  9635.       it's the same as specifying constant text in quotes.
  9636.  
  9637.      ERRORLEVEL
  9638.       
  9639.       0 = Key(s) successfully queued.
  9640.       1 = Keystroke queue full.  You can send 128 keys at a time.
  9641.  
  9642.       If doorway mode is off and you specify one or more Icom hotkeys to carry
  9643.       out tasks, there is no way to tell whether the actual functions/tasks
  9644.       you requested were successful.  If the keys are successfully queued,
  9645.       they are automatically processed.  But since you can do literally
  9646.       anything with SENDKEY there's really no way for Icom to keep track of
  9647.       what occurred and set an errorlevel.  You could cause Icom to process
  9648.       keystrokes for hours, carrying out myriad tasks with a single SENDKEY
  9649.       command.  In such a case, as single errorlevel after the SENDKEY command
  9650.       finally finished, would be meaningless.
  9651.  
  9652.       If you're carrying out critical tasks you're better off using a regular
  9653.  
  9654.  
  9655.  
  9656.  
  9657.      Intellicomm v2.01               SCRIPT.DOC                            151
  9658.      
  9659.      
  9660.  
  9661.       script command which DOES set an errorlevel.  For example, instead of
  9662.       sending the [Alt-D] extended keycode, a couple of 'T's to Tag a BIF or
  9663.       two, then 'D' to dial a BBS... use the DIAL command.  Most Icom
  9664.       functions DO have script command equivalents (DIAL, FILEMAN [and COPY,
  9665.       DELETE, DISKSEARCH, etc.] HELP, HELPSEARCH, SCRIPT, and so forth) to
  9666.       allow you to carry out most of the common Icom tasks without using
  9667.       SENDKEY and looking up keycodes.  Use SENDKEY only when you cannot
  9668.       accomplish the task with regular script commands, or when you want to
  9669.       send an extended keycode to the BBS (with doorway mode on).
  9670.  
  9671.      SEE ALSO
  9672.  
  9673.       $DOORWAY
  9674.  
  9675.       Also see the "SCRIPT COMMANDS AT A GLANCE" section to locate regular
  9676.       script commands which can be used with more reliability/control than
  9677.       using SENDKEY.
  9678.  
  9679.      EXAMPLE
  9680.  
  9681.       variable s       ;define a variable called 's'
  9682.       
  9683.        ;pop a box up allowing up to 70 characters of input
  9684.       BOXGETS s 70 "SENDKEY Example" "Enter some text"
  9685.  
  9686.       SENDKEYS 7680 s 7936 "DEMOFILE.TXT^M^["
  9687.  
  9688.        ;The above sends the [Alt-A] key (access the Editor) then sends the
  9689.        ; contents of variable 's' (whatever the user entered in the input
  9690.        ; box), then sends [Alt-S] (Save File), enters the filename
  9691.        ; DEMOFILE.TXT followed by ENTER (^M = CR) then presses [Esc] (^[ =
  9692.        ; ESC) to exit the editor.  This would only work with the internal
  9693.        ; editor. SENDKEY does not send keys to external programs (it might in
  9694.        ; the future).
  9695.  
  9696.      SENDBREAK________________________________________________________________
  9697.  
  9698.      SUMMARY
  9699.  
  9700.       SENDBREAK [nDURATION]
  9701.  
  9702.      DESCRIPTION
  9703.  
  9704.       Sends a break signal to the current COM port for nDURATION tenths of a
  9705.       second.  If nDURATION is omitted, 30 tenths (3 seconds) is assumed which
  9706.       is the same duration used when [Ctrl-End] is pressed from Terminal mode.
  9707.  
  9708.       No messages are printed to the screen (as with [Ctrl-End] when SENDBREAK
  9709.       is called from a script.  See the example if you want to notify the user
  9710.       that a break is being sent.
  9711.  
  9712.      SEE ALSO
  9713.  
  9714.       RXFLUSH, TXFLUSH
  9715.  
  9716.  
  9717.  
  9718.  
  9719.      Intellicomm v2.01               SCRIPT.DOC                            152
  9720.      
  9721.      
  9722.  
  9723.      EXAMPLE
  9724.  
  9725.       msgopen "Sending break"
  9726.       SENDBREAK
  9727.       msgclose
  9728.  
  9729.      SETCHR___________________________________________________________________
  9730.  
  9731.      SUMMARY
  9732.  
  9733.       SETCHR vTARGETSTRING sCHARACTER nPOSITION
  9734.  
  9735.      DESCRIPTION
  9736.  
  9737.       Places character sCHARACTER into vTARGETSTRING at nPOSITION
  9738.       *overwriting* the existing character in vTARGETSTRING.  Use STRINS to
  9739.       *insert* a character, without overwriting.  For nPOSITION, 0 is the
  9740.       first character in vTARGETSYRING, 1 is the second, etc.  A character
  9741.       must already exist in vTARGETSTRING at nPOSITION.  
  9742.  
  9743.      SEE ALSO
  9744.  
  9745.       SETCHRS, STRINS
  9746.  
  9747.      EXAMPLE
  9748.       
  9749.       variable s "This is a string."
  9750.       SETCHR s "!" 16     ;changes character 16 (.) to !
  9751.  
  9752.       SETCHR s "!" 17     ;does nothing: no character at position 17 to
  9753.      replace
  9754.                           ; use STRCAT to add one or more characters.
  9755.  
  9756.      SETCHRS__________________________________________________________________
  9757.  
  9758.      SUMMARY
  9759.  
  9760.       SETCHRS vTARGETSTRING sNEWSTRING nPOSITION [nNUMCHARS]
  9761.  
  9762.      DESCRIPTION
  9763.  
  9764.       Places nNUMCHARS of sNEWSTRING into into vTARGETSTRING at nPOSITION
  9765.       *overwriting* the existing portion of vTARGETSTRING.  Use STRINS to
  9766.       *insert* a string, without overwriting.  For nPOSITION, 0 is the first
  9767.       character in vTARGETSYRING, 1 is the second, etc.  A string must already
  9768.       exist in vTARGETSTRING, and must be the same size or longer than
  9769.       sNEWSTRING.  I.e. SETCHRS is designed to replace *existing* characters
  9770.       in vTARGETSTRING and not to add new characters to it.  Use STRCAT,
  9771.       STRINS or STRSET to add to an existing string.
  9772.  
  9773.      SEE ALSO
  9774.  
  9775.       SETCHR, STRINS, STRSET
  9776.  
  9777.  
  9778.  
  9779.  
  9780.      Intellicomm v2.01               SCRIPT.DOC                            153
  9781.      
  9782.      
  9783.  
  9784.      EXAMPLE
  9785.       
  9786.       variable s "This is a string."
  9787.       SETCHRS s "replaced" 8
  9788.       print s   ;prints 'This is replaced.'
  9789.  
  9790.       variable s2 "IS A STRING."
  9791.       SETCHRS s s2 5 2    ;at position 5 in 's', only 2 chars from 's2'
  9792.       print s   ;prints 'This IS replaced.' 
  9793.  
  9794.      SETENV___________________________________________________________________
  9795.  
  9796.      SUMMARY
  9797.  
  9798.       SETENV sENVSTRING ...
  9799.  
  9800.      DESCRIPTION
  9801.  
  9802.       Sets a new environment variable or clears an existing environment
  9803.       variable.  Use the format "VARIABLE=setting" to either change an
  9804.       existing environment variable or to add a new variable.  Use the format
  9805.       "VARIABLE=" (no new setting) to clear an existing environment variable.
  9806.  
  9807.      ERRORLEVEL
  9808.  
  9809.       0  SETENV was successful.
  9810.       1  SETENV was unsuccessful.
  9811.  
  9812.      SEE ALSO
  9813.  
  9814.       GETENV
  9815.  
  9816.      EXAMPLE
  9817.  
  9818.       variable path
  9819.  
  9820.       getenv path "PATH"
  9821.       strcat path ";C:\SOMEDIR"
  9822.       setenv "PATH=" path
  9823.  
  9824.      SETCOMM__________________________________________________________________
  9825.  
  9826.      SUMMARY
  9827.  
  9828.       SETCOMM sPORT_SETTINGS ...
  9829.  
  9830.      DESCRIPTION
  9831.  
  9832.       Sets the current COM port ($COM_PORT) to the settings specified by
  9833.       sPORT_SETTINGS.  sPORT_SETTINGS must be in the following format which is
  9834.       specified in one single parameter (spaces are ignored, but the commas
  9835.       [,] are mandatory):
  9836.  
  9837.        "BAUD, PARITY, DATABITS, STOPBITS"
  9838.  
  9839.  
  9840.  
  9841.  
  9842.      Intellicomm v2.01               SCRIPT.DOC                            154
  9843.      
  9844.      
  9845.  
  9846.       BAUD (the port speed or 'baud rate') must be one of the following:
  9847.  
  9848.         300
  9849.         1200
  9850.         2400
  9851.         4800
  9852.         9600
  9853.         19200
  9854.         38400
  9855.         57600
  9856.         115200
  9857.  
  9858.       PARITY must be one of the following (a single letter):
  9859.  
  9860.         N  (No Parity)
  9861.         E  (Even Parity)
  9862.         O  (Odd Parity)
  9863.  
  9864.  
  9865.       DATABITS must be one of the following:
  9866.  
  9867.         7
  9868.         8
  9869.  
  9870.       STOPBITS must be one of the following:
  9871.  
  9872.         1
  9873.         2
  9874.  
  9875.       Any of the above items can be omitted, allowing you to change the Baud
  9876.       without changing the existing Parity, DataBits, StopBits, but the commas
  9877.       are mandatory whether an item is omitted or not.  See the example for
  9878.       details.
  9879.  
  9880.       NOTE: The "..." after the sPORT_SETTINGS parameter means that you can
  9881.       specify multiple parameters which will be grouped together for you as a
  9882.       single parameter.  This allows you to use multiple variables with a
  9883.       single SETCOMM command:
  9884.  
  9885.        variable baud     "9600"
  9886.        variable parity   "N"
  9887.        variable databits "8"
  9888.        variable stopbits "1"
  9889.  
  9890.        SETCOMM baud "," parity "," databits "," stopbits
  9891.  
  9892.       Note that the commas are still mandatory.
  9893.  
  9894.      ERRORLEVEL
  9895.  
  9896.       0  Port settings changed to sPORT_SETTINGS
  9897.       1  Unable to set port to sPORT_SETTINGS (not all combinations of data
  9898.          bits, stop bits and parity are supported by PC COM ports).
  9899.  
  9900.  
  9901.  
  9902.  
  9903.      Intellicomm v2.01               SCRIPT.DOC                            155
  9904.      
  9905.      
  9906.  
  9907.      SEE ALSO
  9908.  
  9909.       PORT, $COM_PORT, $COM_SPEED
  9910.  
  9911.      EXAMPLE
  9912.  
  9913.       SETCOMM "1200,N,8,1" ;1200 BAUD, No PARITY, 8 DATABITS, 1 STOPBIT
  9914.  
  9915.       SETCOMM "19200,,,"   ;set BAUD to 19200, leave PARITY, DATABITS,
  9916.      STOPBITS
  9917.                            ; as is
  9918.  
  9919.       SETCOMM ",E,7,1"     ;leave BAUD as is, set Even PARITY, 7 DATABITS,
  9920.                            ; 1 STOPBIT
  9921.  
  9922.       SETCOMM ",N,,"       ;set PARITY to None, leave all others as is
  9923.  
  9924.      SHL______________________________________________________________________
  9925.  
  9926.      SUMMARY
  9927.  
  9928.       SHL vRESULT nNUM nBITS
  9929.  
  9930.      DESCRIPTION
  9931.  
  9932.       Shifts nBITS bits in nNUM to the left and stores the result in vRESULT. 
  9933.       SHL (SHift Left) is an advanced command for programmers.
  9934.  
  9935.      SEE ALSO
  9936.  
  9937.       SHR
  9938.  
  9939.      EXAMPLE
  9940.  
  9941.       variable result 1
  9942.  
  9943.       SHL result result 1
  9944.       print result   ;prints 2
  9945.  
  9946.       SHL result result 1
  9947.       print result   ;prints 4
  9948.  
  9949.       SHL result result 2
  9950.       print result   ;prints 16
  9951.  
  9952.      SHOWWHENS________________________________________________________________
  9953.  
  9954.      SUMMARY
  9955.  
  9956.       SHOWWHENS
  9957.  
  9958.      DESCRIPTION
  9959.  
  9960.       Displays a screen that shows the current BBS prompts Intellicomm is
  9961.  
  9962.  
  9963.  
  9964.  
  9965.      Intellicomm v2.01               SCRIPT.DOC                            156
  9966.      
  9967.      
  9968.  
  9969.       tracking (either via script WHEN commands, or Intellicomm's automated
  9970.       routines), and the responses or script commands that will be executed
  9971.       when the prompt is found.  Useful in debugging, to display the contents
  9972.       of WHEN slots.  Note that you can also display this screen by pressing
  9973.       [Alt-W] (Show WHENs).
  9974.  
  9975.      SHR______________________________________________________________________
  9976.  
  9977.      SUMMARY
  9978.  
  9979.       SHR vRESULT nNUM nBITS
  9980.  
  9981.      DESCRIPTION
  9982.  
  9983.       Shifts nBITS bits in nNUM to the right and stores the result in vRESULT. 
  9984.       SHR (SHift Right) is an advanced command for programmers.
  9985.  
  9986.      SEE ALSO
  9987.  
  9988.       SHL
  9989.  
  9990.      EXAMPLE
  9991.  
  9992.       variable result 16
  9993.  
  9994.       SHR result result 2
  9995.       print result   ;prints 4
  9996.  
  9997.       SHR result result 1
  9998.       print result   ;prints 2
  9999.  
  10000.       SHR result result 1
  10001.       print result   ;prints 1
  10002.  
  10003.      STAMP____________________________________________________________________
  10004.  
  10005.      SUMMARY
  10006.  
  10007.       STAMP sCOMMENT ...
  10008.  
  10009.      DESCRIPTION
  10010.  
  10011.       Stamps sCOMMENT in the Usage Log (if open).
  10012.  
  10013.      SEE ALSO
  10014.  
  10015.       LOG, LOGCLOSE
  10016.  
  10017.      EXAMPLE
  10018.  
  10019.       variable waiting_for
  10020.  
  10021.       assign waiting_for "Some Text"
  10022.       waitfor waiting_for 120 error
  10023.  
  10024.  
  10025.  
  10026.  
  10027.      Intellicomm v2.01               SCRIPT.DOC                            157
  10028.      
  10029.      
  10030.  
  10031.       return
  10032.  
  10033.      error:
  10034.       STAMP "WAITFOR unable to find text '" waiting_for "' ... hanging up."
  10035.       hangup
  10036.  
  10037.      STRBLANK_________________________________________________________________
  10038.  
  10039.      SUMMARY
  10040.  
  10041.       STRBLANK vSTRING cCOMMAND
  10042.  
  10043.      DESCRIPTION
  10044.  
  10045.       Checks variable vSTRING to see if it is blank (empty or all whitespace). 
  10046.       If vSTRING is blank, cCOMMAND is executed.  If vSTRING is not blank
  10047.       (contains any characters other than spaces, tabs, carriage returns, line
  10048.       feeds, which are known as 'whitespace') cCOMMAND is skipped.
  10049.  
  10050.      SEE ALSO
  10051.  
  10052.       IF
  10053.  
  10054.      EXAMPLE
  10055.  
  10056.       variable input
  10057.  
  10058.      try_again:
  10059.  
  10060.       boxgets input 15 "Attention" "Please enter input"
  10061.  
  10062.       STRBLANK input goto try_again
  10063.  
  10064.      STRCHR___________________________________________________________________
  10065.      STRCHRI__________________________________________________________________
  10066.  
  10067.      SUMMARY
  10068.  
  10069.       STRCHR vPOSITION sSTRING sCHARACTER [nSTART_POSITION]
  10070.  
  10071.      DESCRIPTION
  10072.  
  10073.       Finds the first occurrance of sCHARACTER in string sSTRING.  If
  10074.       sCHARACTER is found, its numeric position in sSTRING is stored in
  10075.       vPOSITION.  If sCHARACTER is not found, -1 is stored in vPOSITION.
  10076.  
  10077.       nSTART_POSITION is an optional position in sSTRING to start the search
  10078.       at.  If omitted, the search begins at the first character (0) in
  10079.       sSTRING.
  10080.  
  10081.       STRCHR is the case sensitive version.  For example, if "a" is specified
  10082.       as sCHARACTER, it will not match "A" if found in sSTRING.
  10083.  
  10084.       STRCHRI is the case insensitive version.  For example, if "a" is
  10085.  
  10086.  
  10087.  
  10088.  
  10089.      Intellicomm v2.01               SCRIPT.DOC                            158
  10090.      
  10091.      
  10092.  
  10093.       specified as sCHARACTER, it will match "A" if found in sSTRING.
  10094.  
  10095.       NOTE: String positions start at zero.  The first character in sSTRING is
  10096.       0, the second character is 1, etc.
  10097.  
  10098.      SEE ALSO
  10099.  
  10100.       STRRCHR, STRRCHRI, STRPOS, STRPOSI, SUBSTR
  10101.  
  10102.      STRCHR EXAMPLE
  10103.  
  10104.       variable s "This is a string."
  10105.       variable pos
  10106.       
  10107.       STRCHR pos s "."  ;would store 16 in 'pos'
  10108.  
  10109.       if pos = -1
  10110.         print "There is no period in '" s "'"
  10111.       else
  10112.         print "There is a period in '" s "'"
  10113.         print "at position: " pos
  10114.         print "But I'm going to get rid of it..."
  10115.         strdel s pos 1    ;a practical use for knowing the position of a given
  10116.                           ; character in a string...
  10117.       endif
  10118.  
  10119.       STRCHR pos s "."   ;this now stores -1 in 'pos' (no more periods)
  10120.  
  10121.       if pos > -1        ;greater than -1 is another way of checking...
  10122.        print "There are no more periods in this string: " s
  10123.       endif
  10124.  
  10125.      STRCHRI EXAMPLE
  10126.  
  10127.       variable s "This is a string."
  10128.       variable pos
  10129.  
  10130.       STRCHRI pos s "S"   ;this stores 3 in 'pos' since the search is case
  10131.                           ; insignificant, and an 's' exists at position 3
  10132.                           ; (remember, the first character is position 0)
  10133.  
  10134.  
  10135.      STRCPY___________________________________________________________________
  10136.  
  10137.      SUMMARY
  10138.  
  10139.       STRCPY vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS]
  10140.  
  10141.      DESCRIPTION
  10142.  
  10143.       Copies nNUMCHARS characters from sSOURCESTR into vTARGETSTR at
  10144.       nPOSITION.  If nPOSITION is omitted, 0 (first position in vTARGETSTR) is
  10145.       assumed.  If nNUMCHARS is omitted all characters from sSOURCESTR are
  10146.       copied.
  10147.  
  10148.  
  10149.  
  10150.  
  10151.      Intellicomm v2.01               SCRIPT.DOC                            159
  10152.      
  10153.      
  10154.  
  10155.       STRCPY is similar to STRINS but it OVERWRITES existing characters in
  10156.       vTARGETSTR instead of pushing existing characters to the right.  STRCPY
  10157.       is also similar to SETCHRS, but where SETCHRS will not truncate
  10158.       vTARGETSTR after nNUMCHARS characters have been copied: STRCPY *will*
  10159.       truncate vTARGETSTR after nNUMCHARS have been copied from sSOURCESTR. 
  10160.       See the example for details.
  10161.  
  10162.       NOTE: String positions start at zero.  The first character in vTARGETSTR
  10163.       is 0, the second character is 1, etc.
  10164.  
  10165.      SEE ALSO
  10166.  
  10167.       SETCHRS, STRINS, STRSET
  10168.  
  10169.      EXAMPLE
  10170.  
  10171.       variable s
  10172.  
  10173.       STRCPY s "ABCDEF"  ;same as ASSIGN s "ABCDEF"
  10174.       STRCPY s "cd" 2
  10175.       print s            ;prints 'ABcd' (the original 'CD' at position 2 is
  10176.                          ; overwritten, and the 'EF' that originally followed
  10177.                          ; is truncated)
  10178.  
  10179.      STRDEL___________________________________________________________________
  10180.  
  10181.      SUMMARY
  10182.  
  10183.       STRDEL vSTRING nPOSITION [nNUMCHARS]
  10184.  
  10185.      DESCRIPTION
  10186.  
  10187.       Deletes nNUMCHARS characters from vSTRING starting at nPOSITION.  If
  10188.       nNUMCHARS is omitted, all characters from nPOSITION on are deleted.
  10189.  
  10190.       If nNUMCHARS is specified and more characters exist to the right of the
  10191.       deleted text, the characters are placed at nPOSITION.  STRDEL works
  10192.       basically the same way that your word processor would work if you put
  10193.       the cursor under a given character on a line (nPOSITION) and pressed the
  10194.       [Delete] key one or more times (nNUMCHARS).  If you omit nNUMCHARS a
  10195.       "Delete to end of line" (or end of string in this case) is performed.
  10196.  
  10197.       NOTE: String positions start at zero.  The first character in vSTRING is
  10198.       0, the second character is 1, etc.
  10199.  
  10200.      SEE ALSO
  10201.  
  10202.  
  10203.       STRINS, STRSET, STRREPLACE, STRREPLACEI, STRSTRIP, STRTRIM
  10204.  
  10205.      EXAMPLE
  10206.  
  10207.       variable s "Want this, don't want this, want this."
  10208.       variable pos
  10209.  
  10210.  
  10211.  
  10212.  
  10213.      Intellicomm v2.01               SCRIPT.DOC                            160
  10214.      
  10215.      
  10216.  
  10217.       variable num
  10218.  
  10219.       strchr pos s ","   ;get position of first comma
  10220.       STRDEL s pos 1     ;kill the first comma
  10221.  
  10222.       strchr num s ","   ;get position of second comma
  10223.       sub num pos        ;this is how many characters to remove if we want
  10224.                          ; to kill everything from 'pos' (originally the
  10225.                          ; first comma) to the second comma.  'pos' must
  10226.                          ; be subtracted from the position of the first
  10227.                          ; comma to get the number of characters to remove
  10228.       STRDEL pos num
  10229.  
  10230.       print s            ;prints 'Want this, want this.'
  10231.  
  10232.      STRINS___________________________________________________________________
  10233.  
  10234.      SUMMARY
  10235.  
  10236.       STRINS vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS]
  10237.  
  10238.      DESCRIPTION
  10239.  
  10240.       Inserts nNUMCHARS characters from sSOURCESTR into vTARGETSTR at
  10241.       nPOSITION.
  10242.  
  10243.       If nPOSITION is omitted, 0 (first character in vTARGETSTR) is assumed.
  10244.  
  10245.       If nNUMCHARS is omitted the entire sSOURCESTR is inserted in vTARGETSTR
  10246.       at nPOSITION.
  10247.  
  10248.       NOTE 1: String positions start at zero.  The first character in vSTRING
  10249.       is 0, the second character is 1, etc.
  10250.  
  10251.       NOTE 2: STRINS pushes existing characters in vTARGETSTR (from nPOSITION
  10252.       onward) to the right to make room for sSOURCESTR.  It does not overwrite
  10253.       existing characters.  If you want to overwrite existing characters in
  10254.       vTARGETSTR, use STRCPY (or STRREPLACE if appropriate).
  10255.  
  10256.      SEE ALSO
  10257.  
  10258.       STRCAT, STRCPY, STRDEL, STRREPLACE, STRREPLACEI
  10259.  
  10260.      EXAMPLE
  10261.  
  10262.       variable s
  10263.  
  10264.       STRINS s "STRINS text" "inserts " 7
  10265.  
  10266.       print s   ;prints 'STRINS inserts text'
  10267.  
  10268.      STRIPSLASH_______________________________________________________________
  10269.  
  10270.      SUMMARY
  10271.  
  10272.  
  10273.  
  10274.  
  10275.      Intellicomm v2.01               SCRIPT.DOC                            161
  10276.      
  10277.      
  10278.  
  10279.       STRIPSLASH vSTRING
  10280.  
  10281.      DESCRIPTION
  10282.  
  10283.       Checks the end of string vSTRING for a trailing backslach (\) and
  10284.       removes it if one exists.  STRIPSLASH is meant to be used mainly with
  10285.       directory names.
  10286.  
  10287.       EXCEPTION: If the character immediately to the left of the trailing
  10288.       slash is a colon (:) the trailing slash is NOT removed.  In directory
  10289.       names, the backslash next to the drive specifier (C:\) is not a
  10290.       'trailing' slash: it's the leading slash (root directory).  Only
  10291.       trailing slashes are removed by STRIPSLASH.  See example for details.
  10292.  
  10293.      SEE ALSO
  10294.  
  10295.       STRDEL, STRSTRIP, STRTRIM
  10296.  
  10297.      EXAMPLE
  10298.  
  10299.       variable s
  10300.  
  10301.       assign s "C:\"
  10302.       STRIPSLASH s
  10303.       prints           ;prints 'C:\' (again, only trailing slashes are
  10304.      removed:
  10305.                        ; and the slash next to the drive designator is not a
  10306.                        ; trailing slash
  10307.  
  10308.       assign s "C:DIR\"
  10309.       STRIPSLASH s
  10310.       print s          ;prints 'C:DIR'
  10311.  
  10312.       assign s "\DIR\"
  10313.       STRIPSLASH s     ;prints '\DIR'
  10314.  
  10315.  
  10316.      STRITEM__________________________________________________________________
  10317.  
  10318.      SUMMARY
  10319.  
  10320.       STRITEM vITEMBUFFER sSEARCHSTRING nITEMNUMBER [sITEMSEPARATOR]
  10321.  
  10322.      DESCRIPTION
  10323.  
  10324.       Searches sSEARCHSTRING for item number nITEMNUMBER and (if found) stores
  10325.       the item in variable vITEMBUFFER.  If sITEMSEPARATOR is omitted, spaces,
  10326.       tabs and semicolons serve as the default item separator, and spaces/tabs
  10327.       enclosed between single or double quotes (' or ") in sSEARCHSTRING are
  10328.       ignored.  If sITEMSEPARATOR is specified, spaces, tabs and semicolons
  10329.       are ignored and only sITEMSEPARATOR serves to separate one item from
  10330.       another in sSEARCHSTRING.
  10331.  
  10332.      ERRORLEVEL
  10333.  
  10334.  
  10335.  
  10336.  
  10337.      Intellicomm v2.01               SCRIPT.DOC                            162
  10338.      
  10339.      
  10340.  
  10341.       0  Item number nITEMNUMBER was found in sSEARCHSTRING and was stored in
  10342.          vITEMBUFFER.
  10343.       1  Item number nITEMNUMBER does not exist in sSEARCHSTRING.
  10344.  
  10345.      EXAMPLE
  10346.  
  10347.         ;In the first three examples, sITEMSEPARATOR is omitted causing
  10348.         ; STRITEM to use spaces and/or tabs and/or semicolons as the
  10349.         ; item separator; unless the space/tab/semicolon is between quotes.
  10350.  
  10351.       variable s "Item1 Item2  Item3   Item4"
  10352.       variable buf
  10353.       variable i
  10354.  
  10355.       STRITEM buf s 3   ;get item 3 from variable 's'
  10356.       print buf         ;prints "Item3" (no quotes)
  10357.  
  10358.       assign s "'Item 1' 'Item 2'  'Item 3'   'Item 4'"
  10359.  
  10360.       STRITEM buf s 3   ;get item 3 from variable 's'
  10361.       print buf         ;prints "Item 3" (no quotes)
  10362.  
  10363.       getenv s "PATH"   ;get the DOS PATH
  10364.       print "Directories on your PATH:"
  10365.  
  10366.       assign i 1        ;start with item 1
  10367.       while 1
  10368.        getitem buf s i
  10369.        if $ERRORLEVEL > 0 break  ;no more items
  10370.        print buf
  10371.        inc i           ;i = i + 1
  10372.       endwhile
  10373.  
  10374.        ;In the following example, sITENSEPARATOR is specified, causing
  10375.        ; STRITEM to ignore all characters other than the specified
  10376.        ; separator character: "^A" (Ctrl-A).  This can be handy to create
  10377.        ; pseudo 'arrays' with strings.... just separator your array members
  10378.        ; with a control character such as ^A.
  10379.  
  10380.       assign s "Item;1^A  Item;2  ^A  Item;3"
  10381.       getitem buf s 2
  10382.       print buf        ;prints "  Item;2  " (no quotes).  I.e. all characters
  10383.                        ; between the 1st and 2nd ^A are considered the 'item'
  10384.       getitem buf s 3
  10385.       print buf        ;prints "  Item;3" (noting simply that a trailing ^A is
  10386.                        ; NOT needed, but you can specify one if desired).
  10387.  
  10388.      STRLEN___________________________________________________________________
  10389.  
  10390.      SUMMARY
  10391.  
  10392.       STRLEN vLENGTH sSTRING [nPOS]
  10393.  
  10394.      DESCRIPTION
  10395.  
  10396.  
  10397.  
  10398.  
  10399.      Intellicomm v2.01               SCRIPT.DOC                            163
  10400.      
  10401.      
  10402.  
  10403.       Stores the length of string sSTRING from nPOS onward in variable
  10404.       vLENGTH.  If nPOS is omitted, 0 (the beginning of string sSTRING) is
  10405.       assumed.  If nPOS is specified, STRLEN counts the number of characters
  10406.       from nPOS onwards.
  10407.  
  10408.       NOTE: String positions start at zero.  The first character in sSTRING is
  10409.       0, the second character is 1, etc.
  10410.  
  10411.      EXAMPLE
  10412.  
  10413.       variable s "12345"
  10414.       variable len
  10415.  
  10416.       STRLEN len s
  10417.       print len      ;prints '5'
  10418.  
  10419.      STRLOWER_________________________________________________________________
  10420.  
  10421.      SUMMARY
  10422.  
  10423.       STRLOWER vSTRING
  10424.  
  10425.      DESCRIPTION
  10426.  
  10427.       Converts all UPPERCASE characters in vSTRING to lowercase.
  10428.  
  10429.      SEE ALSO
  10430.  
  10431.       STRUPPER
  10432.  
  10433.      EXAMPLE
  10434.  
  10435.       variable s "THIS IS A STRING"
  10436.  
  10437.       STRLOWER s
  10438.       print s        ;prints 'this is a string'
  10439.  
  10440.      STRCAT___________________________________________________________________
  10441.  
  10442.      SUMMARY
  10443.  
  10444.       STRCAT vTARGETSTR sSOURCESTR ...
  10445.  
  10446.      DESCRIPTION
  10447.  
  10448.       Concatenates sSOURCESTR to vTARGETSTR (in English, it adds sSOURCESTR to
  10449.       the end of vTARGETSTR).
  10450.  
  10451.      SEE ALSO
  10452.  
  10453.       STRCPY, STRINS
  10454.  
  10455.      EXAMPLE
  10456.  
  10457.  
  10458.  
  10459.  
  10460.      Intellicomm v2.01               SCRIPT.DOC                            164
  10461.      
  10462.      
  10463.  
  10464.       variable dir1 "C:\DIR1"
  10465.       variable dir2 "C:\DIR2"
  10466.  
  10467.       strcat dir1 ";" dir2
  10468.       print dir1              ;prints 'C:\DIR1;C:\DIR2'
  10469.  
  10470.      STRPAD___________________________________________________________________
  10471.  
  10472.      SUMMARY
  10473.  
  10474.       STRPAD vSTRING sPADCHAR nNEWLENGTH
  10475.  
  10476.      DESCRIPTION
  10477.  
  10478.       Pads the left side of vSTRING with sPADCHAR to make it nNEWLENGTH
  10479.       characters long.  sPADCHAR will normally be " " (a space) to pad a
  10480.       string to a given length for the purpose of lining things up on the
  10481.       screen (PRINT, so that everything is the same length; filenames for
  10482.       example) or writing them to a text file.
  10483.  
  10484.      SEE ALSO
  10485.  
  10486.       STRPADL, STRTRIM
  10487.  
  10488.      EXAMPLE 1
  10489.  
  10490.       variable s "Pad me"
  10491.  
  10492.       STRPAD s "!" 6
  10493.       print s          ;prints 'Pad me' (no change since s is already 6
  10494.                        ; characters long)
  10495.       STRPAD s "!" 10
  10496.       print s          ;prints 'Pad me!!!!'
  10497.  
  10498.      EXAMPLE 2
  10499.  
  10500.       variable f
  10501.       variable s
  10502.       
  10503.       fopen f "MYDATA.DAT" "w"
  10504.  
  10505.       boxgets s 30 "" "Enter Something"
  10506.       STRPAD s " " 30                    ;make it 30 characters long, padding
  10507.                                          ; with spaces (which can be easily
  10508.                                          ; removed with STRTRIM)
  10509.       fputs f s                          ;write it to the file
  10510.       fclose f
  10511.  
  10512.        ;Padding data before writing it to a file is a common technique
  10513.        ; explained in "INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC
  10514.  
  10515.      STRPADL__________________________________________________________________
  10516.  
  10517.      SUMMARY
  10518.  
  10519.  
  10520.  
  10521.  
  10522.      Intellicomm v2.01               SCRIPT.DOC                            165
  10523.      
  10524.      
  10525.  
  10526.       STRPAD vSTRING sPADCHAR nNEWLENGTH
  10527.  
  10528.      DESCRIPTION
  10529.  
  10530.       Pads the right side of vSTRING with sPADCHAR to make it nNEWLENGTH
  10531.       characters long.  sPADCHAR will normally be " " (a space) to pad a
  10532.       string to a given length for the purpose of lining things up on the
  10533.       screen (PRINT, so that everything is the same length; filenames for
  10534.       example) or writing them to a text file.  STRPADL is most often used
  10535.       with numbers, to right justify them:
  10536.  
  10537.             1    <-- Pad the left side with X number of spaces to line up
  10538.          1234
  10539.         12345
  10540.  
  10541.      SEE ALSO
  10542.  
  10543.       STRPAD, STRLTRIM
  10544.  
  10545.      EXAMPLE 1
  10546.  
  10547.       variable n1 "1"
  10548.       variable n2 "12"
  10549.       variable n3 "123"
  10550.  
  10551.       STRPAD n1 " " 5
  10552.       STRPAD n2 " " 5
  10553.       STRPAD n3 " " 5
  10554.  
  10555.       print n1         ;prints '    1'
  10556.       print n2         ;prints '   12'
  10557.       print n3         ;prints '  123'
  10558.  
  10559.      STRSET___________________________________________________________________
  10560.  
  10561.      SUMMARY
  10562.  
  10563.       STRSET vTARGETSTR sCHAR nPOSITION nNUM
  10564.  
  10565.      DESCRIPTION
  10566.  
  10567.       Sets nNUM characters of vTARGETSTR to the character sCHAR at nPOSITION. 
  10568.       STRSET is meant to be used to quickly set a string to a given character
  10569.       for drawing lines, or filling the screen with a given character, etc. 
  10570.       See SCRDEMO.SCR for an example.
  10571.  
  10572.       STRSET is not meant to be used to overwrite the middle of a string with
  10573.       a given character: when it finishes writing the last sCHAR character it
  10574.       truncates vTARGETSTR right there.  Use SETCHR to overwrite a portion of
  10575.       a string without truncating it.
  10576.  
  10577.      SEE ALSO
  10578.  
  10579.       SETCHR, SETCHRS
  10580.  
  10581.  
  10582.  
  10583.  
  10584.      Intellicomm v2.01               SCRIPT.DOC                            166
  10585.      
  10586.      
  10587.  
  10588.      EXAMPLE
  10589.       
  10590.       variable s
  10591.  
  10592.       STRSET s "▓" 0 70      ;fill 's' with 70 "▓" characters
  10593.       setchrs s " Hello! " 31 8
  10594.       print s                ;this prints:
  10595.  
  10596.       ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ Hello! ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  10597.  
  10598.      STRPOS___________________________________________________________________
  10599.  
  10600.      SUMMARY
  10601.  
  10602.       STRPOS vPOSITION sSTRING sSEARCHSTR
  10603.  
  10604.      DESCRIPTION
  10605.  
  10606.       Searches string sSTRING for the string sSEARCHSTR.  If found, the
  10607.       position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. 
  10608.       If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1).
  10609.  
  10610.       Case is significant when searching for sSEARCHSTR: "ABC" will not match
  10611.       "abc" or "Abc".  Use STRPOSI for a case insensitive search.
  10612.  
  10613.       NOTE: String positions start at zero.  The first character in vSTRING is
  10614.       0, the second character is 1, etc.
  10615.  
  10616.      SEE ALSO
  10617.  
  10618.       STRPOSI
  10619.  
  10620.      EXAMPLE
  10621.  
  10622.       variable s "ABCDEFGH"
  10623.       variable pos
  10624.       
  10625.       STRPOS pos s "DEF"   ;this stores 3 in 'pos'
  10626.  
  10627.       if pos = -1
  10628.         print "DEF does not exist."
  10629.       else
  10630.         print "DEF exists at position " pos
  10631.       endif
  10632.  
  10633.      STRPOSI__________________________________________________________________
  10634.  
  10635.      SUMMARY
  10636.  
  10637.       STRPOSI vPOSITION sSTRING sSEARCHSTR
  10638.  
  10639.      DESCRIPTION
  10640.  
  10641.       Searches string sSTRING for the string sSEARCHSTR.  If found, the
  10642.  
  10643.  
  10644.  
  10645.  
  10646.      Intellicomm v2.01               SCRIPT.DOC                            167
  10647.      
  10648.      
  10649.  
  10650.       position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. 
  10651.       If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1).
  10652.  
  10653.       Case is insignificant when searching for sSEARCHSTR: "ABC" will match
  10654.       "abc" or "Abc".  Use STRPOS for a case sensitive search.
  10655.  
  10656.       NOTE: String positions start at zero.  The first character in vSTRING is
  10657.       0, the second character is 1, etc.
  10658.  
  10659.      SEE ALSO
  10660.  
  10661.       STRPOS
  10662.  
  10663.      EXAMPLE
  10664.  
  10665.       variable s "ABCDEFGH"
  10666.       variable pos
  10667.       
  10668.       STRPOS pos s "def"   ;this stores 3 in 'pos'
  10669.  
  10670.       if pos = -1
  10671.         print "DEF does not exist."
  10672.       else
  10673.         print "DEF exists at position " pos
  10674.       endif
  10675.  
  10676.      STRRCHR__________________________________________________________________
  10677.      STRRCHRI_________________________________________________________________
  10678.  
  10679.      SUMMARY
  10680.  
  10681.       STRRCHR vPOSITION sSTRING sCHARACTER
  10682.       STRRCHRI vPOSITION sSTRING sCHARACTER
  10683.  
  10684.      DESCRIPTION
  10685.  
  10686.       Finds the *last* occurrance of sCHARACTER in sSTRING.  If sCHARACTER is
  10687.       found, its numeric position in sSTRING is stored in variable vPOSITION. 
  10688.       If sCHARACTER is not found, -1 is stored in vPOSITION.
  10689.  
  10690.       STRRCHR is the case sensitive version.  For example, if "a" is specified
  10691.       as sCHARACTER, it will not match "A" if found in sSTRING.
  10692.  
  10693.       STRRCHRI is the case insensitive version.  For example, if "a" is
  10694.       specified as sCHARACTER, it will match "A" if found in sSTRING.
  10695.  
  10696.       NOTE: String positions start at zero.  The first character in sSTRING is
  10697.       0, the second character is 1, etc.
  10698.  
  10699.      SEE ALSO
  10700.  
  10701.       STRCHR, STRCHRI, STRPOS, STRPOSI, SUBSTR
  10702.  
  10703.      STRRCHR EXAMPLE
  10704.  
  10705.  
  10706.  
  10707.  
  10708.      Intellicomm v2.01               SCRIPT.DOC                            168
  10709.      
  10710.      
  10711.  
  10712.        variable pos
  10713.        variable s "This is a string"
  10714.        variable s2
  10715.  
  10716.        STRRCHR pos s " "   ;finds the LAST space in variable 's'
  10717.  
  10718.        if pos = -1
  10719.         print "No spaces exist in 's'"
  10720.        else
  10721.         inc pos            ;pos = pos + 1 (get past the space)
  10722.         substr s2 s
  10723.        endif
  10724.  
  10725.      STRRCHRI EXAMPLE
  10726.  
  10727.  
  10728.      STRREPLACE_______________________________________________________________
  10729.      STRREPLACEI______________________________________________________________
  10730.  
  10731.      SUMMARY
  10732.  
  10733.       STRREPLACE vTARGETSTR sSEARCHSTR sREPLACESTR
  10734.       STRREPLACEI vTARGETSTR sSEARCHSTR sREPLACESTR
  10735.  
  10736.      DESCRIPTION
  10737.  
  10738.       Searches vTARGETSTR for all occurrances of sSEARCHSTR and replaces them
  10739.       with sSREPLACESTR.  SRREPLACE is case sensitive (occurrances of "abc"
  10740.       will not replace occurrances of "ABC") while STRREPLACEI is case
  10741.       insensitive (occurrances of "abc" will replace occurrances of "ABC")
  10742.  
  10743.      SEE ALSO
  10744.  
  10745.       STRPOS, STRPOSI
  10746.  
  10747.      STRREPLACE EXAMPLE
  10748.  
  10749.       variable s "IBM XT"
  10750.  
  10751.       STRREPLACE s "xt" "486"
  10752.       print s                  ;prints 'IBM XT' (no change since STRREPLACE
  10753.                                ; is case sensitive and "xt" doesn't match "XT"
  10754.  
  10755.       strreplace s "XT" "486"
  10756.       print s                  ;prints 'IBM 486'
  10757.  
  10758.      STRREPLACEI EXAMPLE
  10759.  
  10760.       variable s "IBM XT"
  10761.  
  10762.       STRREPLACEI s "xt" "486"
  10763.       print s                  ;prints 'IBM 486'
  10764.  
  10765.      STRSTRIP_________________________________________________________________
  10766.  
  10767.  
  10768.  
  10769.  
  10770.      Intellicomm v2.01               SCRIPT.DOC                            169
  10771.      
  10772.      
  10773.  
  10774.      SUMMARY
  10775.  
  10776.       STRSTRIP vSTRING sCHAR
  10777.  
  10778.      DESCRIPTION
  10779.  
  10780.       Strips all occurrances of character sCHAR from string vSTRING.
  10781.  
  10782.      SEE ALSO
  10783.  
  10784.       STRDEL, STRTRIM
  10785.  
  10786.      EXAMPLE
  10787.  
  10788.       variable s "This is a string"
  10789.  
  10790.       STRSTRIP s " "   ;strip all spaces
  10791.       print s          ;prints 'Thisisastring'
  10792.  
  10793.      STRBTRIM_________________________________________________________________
  10794.      STRLTRIM_________________________________________________________________
  10795.      STRTRIM__________________________________________________________________
  10796.  
  10797.      SUMMARY
  10798.  
  10799.       STRBTRIM vSTRING
  10800.       STRLTRIM vSTRING
  10801.       STRTRIM vSTRING
  10802.  
  10803.      DESCRIPTION
  10804.  
  10805.       The STRxTRIM commands are used to trim extra whitespace characters from
  10806.       string vSTRING.
  10807.  
  10808.       STRBTRIM trims whitespace from both sides of vSTRING.
  10809.       STRLTRIM trims whitespace only from the left side of vSTRING.
  10810.       STRTRIM  trims whitespace only from the right side of vSTRING.
  10811.  
  10812.       ['Whitespace' includes spaces, tabs, carriage returns, line feeds and
  10813.       form feeds.]
  10814.  
  10815.      SEE ALSO
  10816.  
  10817.       STRDEL, STRSTRIP
  10818.  
  10819.      EXAMPLE
  10820.  
  10821.       variable s
  10822.  
  10823.       assign s "  string data  "
  10824.       STRBTRIM s
  10825.       print s                    ;prints 'string data'
  10826.  
  10827.       assign s "  string data  "
  10828.  
  10829.  
  10830.  
  10831.  
  10832.      Intellicomm v2.01               SCRIPT.DOC                            170
  10833.      
  10834.      
  10835.  
  10836.       STRLTRIM s
  10837.       print s                    ;prints 'string data  '
  10838.  
  10839.       assign s "  string data  "
  10840.       STRTRIM s
  10841.       print s                    ;prints '  string data'
  10842.  
  10843.      STRUPPER_________________________________________________________________
  10844.  
  10845.      SUMMARY
  10846.  
  10847.       STRUPPER vSTRING
  10848.  
  10849.      DESCRIPTION
  10850.  
  10851.       Converts all lowercase characters in vSTRING to UPPERCASE.
  10852.  
  10853.      SEE ALSO
  10854.  
  10855.       STRLOWER
  10856.  
  10857.      EXAMPLE
  10858.  
  10859.       variable s "this is a string"
  10860.       STRUPPER s
  10861.       print s        ;prints 'THIS IS A STRING'
  10862.  
  10863.      SUB______________________________________________________________________
  10864.  
  10865.      SUMMARY
  10866.  
  10867.       SUB vREMAINDER nMINUEND nSUBTRAHEND
  10868.  
  10869.      DESCRIPTION
  10870.  
  10871.       Minuend and subtrahend?  Well, that's what my old college math book
  10872.       says.  <grin>  SUBtracts nSUBTRAHEND from nMINUEND and stores the result
  10873.       in nREMAINDER.  If you somehow forgot which number is called the
  10874.       'subtrahend' and which is the 'minuend':
  10875.  
  10876.          10   <-- Minuend
  10877.        -  5   <-- Subtrahend
  10878.        ----
  10879.           5   <-- Remainder (or Difference)
  10880.  
  10881.       We learn something new every day...
  10882.  
  10883.      SEE ALSO
  10884.  
  10885.       ADD, DIV, MUL, SUB
  10886.  
  10887.      EXAMPLE
  10888.  
  10889.       variable result
  10890.  
  10891.  
  10892.  
  10893.  
  10894.      Intellicomm v2.01               SCRIPT.DOC                            171
  10895.      
  10896.      
  10897.  
  10898.       SUB result 10 5  ;stores 10 - 5 (5) in variable 'result'
  10899.       print result
  10900.  
  10901.      SUBSTR___________________________________________________________________
  10902.  
  10903.      SUMMARY
  10904.  
  10905.       SUBSTR vTARGET sSOURCE nPOSITION [nNUM]
  10906.  
  10907.      DESCRIPTION
  10908.  
  10909.       Copies nNUM characters from nPOSITION in string sSOURCE to variable
  10910.       vTARGET.  If nNUM is specified, all characters from nNUM position in
  10911.       sSOURCE are counted.  If nNUM is omitted, 0 (the beginning of sSOURCE)
  10912.       is assumed.
  10913.  
  10914.       NOTE: String positions start at zero.  The first character in vSTRING is
  10915.       0, the second character is 1, etc.
  10916.  
  10917.      SEE ALSO
  10918.  
  10919.       STRCPY
  10920.  
  10921.      EXAMPLE
  10922.  
  10923.       variable s
  10924.  
  10925.       SUBSTR s "This is a string!" 10 6
  10926.       print s                            ;prints 'string'
  10927.  
  10928.  
  10929.      SWITCH___________________________________________________________________
  10930.       CASE____________________________________________________________________
  10931.       ENDCASE_________________________________________________________________
  10932.       DEFAULT_________________________________________________________________
  10933.       ENDSWITCH_______________________________________________________________
  10934.  
  10935.      SUMMARY
  10936.  
  10937.       SWITCH vVARIABLE
  10938.        CASE
  10939.        [CASE]
  10940.        [...]
  10941.          cCOMMAND
  10942.          [cCOMMAND]
  10943.          [...]
  10944.        ENDCASE
  10945.        [CASE]
  10946.        [...]
  10947.          [cCOMMAND]
  10948.          [...]
  10949.        [ENDCASE]
  10950.        [DEFAULT]
  10951.          [cCOMMAND]
  10952.  
  10953.  
  10954.  
  10955.  
  10956.      Intellicomm v2.01               SCRIPT.DOC                            172
  10957.      
  10958.      
  10959.  
  10960.          [...]
  10961.        [ENDCASE]
  10962.       ENDSWITCH
  10963.  
  10964.      DESCRIPTION
  10965.  
  10966.       Compares the contents of vVARIABLE for equality to the CASE
  10967.       statement(s).  If a match is found, the command(s) between the matching
  10968.       CASE/ENDCASE are executed.  If no match is found, and a DEFAULT case is
  10969.       specified, the commands between DEFAULT/ENDCASE are executed.  If no
  10970.       DEFAULT is specified and no matching CASE is found, all commands between
  10971.       SWITCH/ENDCASE are ignored.
  10972.  
  10973.       SWITCH is used when comparing many conditions (such as menu selections),
  10974.       where using IF/ELSE/ENDIF would be impractical.
  10975.  
  10976.      ERRORLEVEL
  10977.  
  10978.       SWITCH, ENDSWITCH, CASE, ENDCASE, DEFAULT do not change $ERRORLEVEL.
  10979.  
  10980.      SEE ALSO
  10981.  
  10982.       IF, WHILE
  10983.  
  10984.      NUMERIC SWITCH EXAMPLE
  10985.  
  10986.       menudefine "Option ~1" "Option ~2" "Option ~3" "e~Xit"
  10987.       menuboxv "Menu" "Select an option"
  10988.  
  10989.       SWITCH $MENUSELECTION
  10990.         CASE 1                ;is $MENUSELECTION equal to 1?
  10991.  
  10992.           print "Option 1 was selected."
  10993.           ;you can carry out any number of commands here before the ENDCASE
  10994.         ENDCASE
  10995.         CASE 2                ;is $MENUSELECTION equal to 2?
  10996.           print "Option 2 was selected."
  10997.         ENDCASE
  10998.         CASE 3                ;is $MENUSELECTION equal to 3?
  10999.           print "Option 3 was selected."
  11000.         ENDCASE
  11001.         DEFAULT
  11002.           print "[Esc] was pressed, or eXit was selected."
  11003.         ENDCASE
  11004.       ENDSWITCH
  11005.  
  11006.      STRING SWITCH EXAMPLE
  11007.  
  11008.       variable old_dir $CUR_DIR
  11009.       variable fname
  11010.       variable ext
  11011.  
  11012.       findfirst fname "*.*"
  11013.  
  11014.  
  11015.  
  11016.  
  11017.      Intellicomm v2.01               SCRIPT.DOC                            173
  11018.      
  11019.      
  11020.  
  11021.       while $ERRORLEVEL = 0          ;while a file is found
  11022.         fnstrip ext fname 15         ;get file .EXT (extension)
  11023.  
  11024.         SWITCH ext
  11025.           CASE ".ZIP"                ;is 'ext' equal to ".ZIP" ?
  11026.             dos "PKZIP /v " fname 
  11027.           ENDCASE
  11028.           CASE ".ARJ"                ;is 'ext' equal to ".ARJ" ?
  11029.             dos "ARJ l " fname 
  11030.           ENDCASE
  11031.           CASE ".LHA"                ;is 'ext' equal to ".LHA" ?
  11032.             dos "LHA l " fname
  11033.           ENDCASE
  11034.           DEFAULT
  11035.             print fname " is not a .ZIP, .ARJ, or .LHA file."
  11036.           ENDCASE
  11037.         ENDSWITCH
  11038.  
  11039.         findnext fname
  11040.       endwhile
  11041.  
  11042.      SYSTEM___________________________________________________________________
  11043.  
  11044.      SUMMARY
  11045.  
  11046.       SYSTEM [nHANGUP] [nERRORLEVEL]
  11047.  
  11048.      DESCRIPTION
  11049.  
  11050.       SYSTEM closes the current COM port (if open), closes all files, etc.,
  11051.       hangs up/stays connected or asks the user what to do, then exits back to
  11052.       the 'caller'.  The caller could be DOS, or a .BAT file, or a menu system
  11053.       (Windows, DESQview, etc): whatever called ICOM.EXE originally.  
  11054.  
  11055.       nHANGUP is optional and can be either 1 (hangup unconditionally), or 2
  11056.       (stay connected) or 0/any other number (or nothing) which causes SYSTEM
  11057.       to ask the user whether to disconnect, if connected.
  11058.  
  11059.       nERRORLEVEL is an optional error code which can be tested with the .BAT
  11060.       ERRORLEVEL statement.  See the example for usage.
  11061.  
  11062.      SEE ALSO
  11063.  
  11064.       EXIT
  11065.  
  11066.      EXAMPLE
  11067.  
  11068.       send "SOME COMMAND"
  11069.       waitfor "Some BBS Prompt" 120 ERROR
  11070.       SYSTEM              ;exit with no errorlevel, asking the user whether to
  11071.                           ;disconnect or not (SYSTEM 0 0 does the same)
  11072.  
  11073.      ERROR:
  11074.       SYSTEM 1 1          ;hangup, exit to DOS with errorlevel set to 1
  11075.  
  11076.  
  11077.  
  11078.  
  11079.      Intellicomm v2.01               SCRIPT.DOC                            174
  11080.      
  11081.      
  11082.  
  11083.      ;If you called a script like this from a .BAT file, you could test the
  11084.      ;ERRORLEVEL to see whether the script was successful or not:
  11085.      ;
  11086.      ; rem SOMEBAT.BAT
  11087.      ; ICOM.EXE /scr:MYSCRIPT.SCR
  11088.      ; if errorlevel 1 goto ERROR
  11089.      ; rem No errors, do whatever needs doing here
  11090.      ; :ERROR
  11091.  
  11092.      TAGGER___________________________________________________________________
  11093.  
  11094.      SUMMARY
  11095.  
  11096.       TAGGER [sCATALOG]
  11097.  
  11098.      DESCRIPTION
  11099.  
  11100.       Enters the File Tagger.  If sCATALOG is specified, the catalog is loaded
  11101.       for viewing.  If sCATALOG is omitted, the NEWFILES catalog is loaded.
  11102.  
  11103.       NOTE: Control will not return to your script until the user exits the
  11104.       File Tagger.
  11105.  
  11106.      SEE ALSO
  11107.  
  11108.       DIAL, FILEMAN, SCRIPT
  11109.  
  11110.      EXAMPLE
  11111.  
  11112.       pause "Enter the File Tagger to Tag files for uploading..."
  11113.       TAGGER "FILELIST"
  11114.  
  11115.      TERMINAL_________________________________________________________________
  11116.  
  11117.      SUMMARY
  11118.  
  11119.       TERMINAL
  11120.  
  11121.      DESCRIPTION
  11122.  
  11123.       TERMINAL is an advanced command that won't be needed by most script
  11124.       writers.  If your script is having problems in that it doesn't display
  11125.       characters from the BBS and doesn't process keystrokes (i.e. [Alt-Z] to
  11126.       call up the Terminal menu), then TERMINAL will solve the problem. 
  11127.       Otherwise, only read this if you're not faint-of-heart and are looking
  11128.       to conquer the entire script language.
  11129.  
  11130.       The TERMINAL command makes a call to Icom's "terminal handler", which is
  11131.       the Icom function that gets and handles characters from the COM port (if
  11132.       any), and processes user keystrokes and mouse clicks (if any).  To make
  11133.       scripts easier to write, TERMINAL is automatically called for you in the
  11134.       following locations:
  11135.  
  11136.        + After a HANGUP command.
  11137.  
  11138.  
  11139.  
  11140.  
  11141.      Intellicomm v2.01               SCRIPT.DOC                            175
  11142.      
  11143.      
  11144.  
  11145.        + After a PORT command.
  11146.        + After a SEND, SENDNC, SENDNP, SENDNCP command.
  11147.        + After a SENDBIF command.
  11148.        + After a SETCOMM command.
  11149.        + Repeatedly during a WAITFOR command.
  11150.        + After a WAITUNTIL command.
  11151.  
  11152.       [During some other commands, such as UPLOAD and DOWNLOAD, the TERMINAL
  11153.       command is not used... but characters are still sent/received.  All
  11154.       protocols deal directly with the COM port without going through the
  11155.       terminal.]
  11156.  
  11157.       WITHOUT this automatic use of the TERMINAL command, nothing from the BBS
  11158.       would ever be displayed on the screen while your script was running
  11159.       (characters would simply fill up Icom's internal receive buffer until
  11160.       flow control was activated).  With Icom v1, before script 'loops' were
  11161.       introduced, it was almost impossible to run into a situation where Icom
  11162.       wouldn't call TERMINAL automatically through one script command or
  11163.       another, for longer than a millisecond or two.  With the v2 script
  11164.       language it's possible to enter a WHILE loop and NEVER call the TERMINAL
  11165.       handler (depending on how long the loop executes for and what commands
  11166.       you execute in the loop).  When in a loop, and not using any of the
  11167.       above commands which automatically call TERMINAL for you, do this if you
  11168.       want the terminal display to be updated in your loop:
  11169.  
  11170.        WHILE <condition>   ;some valid WHILE condition
  11171.          TERMINAL          ;call the TERMINAL handler
  11172.          ...               ;then do whatever it is you're doing in the loop
  11173.        ENDWHILE
  11174.  
  11175.       ...or, if you don't use loops and still have problems, simply place a
  11176.       few TERMINAL commands randomly around your script until it works. 
  11177.       *Each* TERMINAL command in your script will empty the entire Receive
  11178.       Buffer to the screen, and process any waiting keystrokes: both of which
  11179.       are buffered until they're handled by a call to TERMINAL.
  11180.  
  11181.       Another way to look at the TERMINAL command is that by NOT calling it,
  11182.       and by not using script commands that call it automatically (i.e. SEND,
  11183.       etc), you can PREVENT BBS characters from being displayed on the screen
  11184.       and can intercept keystrokes that would otherwise go to the Terminal
  11185.       handler (also see the $KEY_CHECK variable).  You needn't worry about
  11186.       losing data from the BBS while you're not using TERMINAL... at least as
  11187.       long as you've got your "Flow Control" set up properly on your modem and
  11188.       in Icom ("Software flow control": XON/XOFF, etc., or "Hardware flow
  11189.       control": CTS/RTS, etc).  Icom has a program called an "interrupt
  11190.       handler" that runs in the background, and is executed and driven
  11191.       entirely by the computer hardware (the COM port), to process incoming
  11192.       characters from the BBS.  When a character is received from the modem,
  11193.       the COM port sends an interrupt, which in turn causes your processor to
  11194.       call Intellicomm's interrupt handler, which in turn places the character
  11195.       into Icom's internal "Receive Buffer" (the size is configurable in the
  11196.       main setup; it defaults to 4 Kbytes).  When the receive buffer is about
  11197.       80% full, Icom's interrupt handler activates "flow control", telling the
  11198.       modem (and the BBS) to STOP sending data, and this will happen whether
  11199.  
  11200.  
  11201.  
  11202.  
  11203.      Intellicomm v2.01               SCRIPT.DOC                            176
  11204.      
  11205.      
  11206.  
  11207.       you call TERMINAL or not.  [Sometimes it takes a second or two for the
  11208.       BBS to stop sending, and that's why flow control is activated when the
  11209.       buffer is 80% full instead of waiting until it's ready to overflow.] 
  11210.       The characters in the Receive Buffer (and keystrokes/mouse clicks in the
  11211.       keystroke buffer) simply won't be displayed to the screen or acted
  11212.       upon... they'll sit in the Receive Buffer waiting for you to call
  11213.       TERMINAL.
  11214.  
  11215.      EXAMPLE
  11216.  
  11217.       variable key          ;define a variable to hold keystrokes
  11218.       variable old_kcheck $KEY_CHECK
  11219.  
  11220.       assign $KEY_CHECK 0   ;shut off the Terminal's keystroke handler
  11221.  
  11222.       msgopen "I'm not doing anything until you press [Esc]!"
  11223.  
  11224.        ;since there is no TERMINAL command in this loop, and
  11225.        ;since INKEY doesn't call TERMINAL automatically, nothing
  11226.        ;from the BBS is displayed on the screen, and no keystrokes
  11227.        ;(other than ESC) are processed.  Total control...
  11228.  
  11229.       WHILE key <> "^["    ;while key is not equal to the ESC key
  11230.        inkey key
  11231.       ENDWHILE
  11232.       
  11233.       msgclose
  11234.       assign $KEY_CHECK old_kcheck
  11235.       TERMINAL             ;kaboom, all characters received from the modem
  11236.                            ; during the pause are now displayed rapidly
  11237.  
  11238.       Alternatively, instead of calling TERMINAL, you could also use CGETC and
  11239.       process characters one at a time in a loop.
  11240.  
  11241.      TIMER____________________________________________________________________
  11242.  
  11243.      SUMMARY
  11244.  
  11245.       TIMER [nTENTHS]
  11246.  
  11247.      DESCRIPTION
  11248.  
  11249.       Starts a timer that will expire in nTENTHS of a second.  Use TIMEUP to
  11250.       determine whether the timer has expired.  Multiple calls to TIMER
  11251.       cancels the previous TIMER command (if any).
  11252.  
  11253.       If nTENTHS is zero or omitted, the timer never expires (until the script
  11254.       ends).
  11255.  
  11256.      SEE ALSO
  11257.  
  11258.       TIMERTOTAL, TIMEUP
  11259.  
  11260.      EXAMPLE
  11261.  
  11262.  
  11263.  
  11264.  
  11265.      Intellicomm v2.01               SCRIPT.DOC                            177
  11266.      
  11267.      
  11268.  
  11269.       TIMER 100      ;100 tenths (10 seconds)
  11270.  
  11271.       msgopen "Waiting 10 seconds..."
  11272.       while 1
  11273.        timeup break
  11274.       endwhile
  11275.       msgclose
  11276.  
  11277.      TIMERTOTAL_______________________________________________________________
  11278.  
  11279.      SUMMARY
  11280.  
  11281.       TIMERTOTAL vTOTAL
  11282.  
  11283.      DESCRIPTION
  11284.  
  11285.       Stores in vTOTAL the total tenths of a second that have elapsed since
  11286.       the last TIMER command.
  11287.  
  11288.      SEE ALSO
  11289.  
  11290.       TIMER, TIMEUP
  11291.  
  11292.      EXAMPLE
  11293.  
  11294.       variable total
  11295.  
  11296.       cls
  11297.       timer
  11298.  
  11299.       while 1
  11300.        timertotal total
  11301.        printraw 1 1 $SCRN_COLOR "TIMERTOTAL: " total
  11302.        if total > 100 break                         ;break after 10 seconds
  11303.       endwhile
  11304.  
  11305.      TIMEUP___________________________________________________________________
  11306.  
  11307.      SUMMARY
  11308.  
  11309.       TIMEUP cCOMMAND
  11310.  
  11311.      DESCRIPTION
  11312.  
  11313.       If the last timer started with the TIMER command has expired, cCOMMAND
  11314.       is executed.  If the timer has not expired, cCOMMAND is skipped.
  11315.  
  11316.      SEE ALSO
  11317.  
  11318.       TIMER, TIMERTOTAL
  11319.  
  11320.      EXAMPLE
  11321.  
  11322.       timer 100      ;100 tenths (10 seconds)
  11323.  
  11324.  
  11325.  
  11326.  
  11327.      Intellicomm v2.01               SCRIPT.DOC                            178
  11328.      
  11329.      
  11330.  
  11331.       msgopen "Waiting 10 seconds..."
  11332.       while 1
  11333.        TIMEUP break
  11334.       endwhile
  11335.       msgclose
  11336.  
  11337.      TONE_____________________________________________________________________
  11338.  
  11339.      SUMMARY
  11340.  
  11341.       TONE nFREQUENCY nDURATION
  11342.  
  11343.      DESCRIPTION
  11344.  
  11345.       Sounds a tone of nFREQUENCY for nDURATION tenths of a second on the PC
  11346.       Speaker.  The higher the number is for nFREQUENCY, the higher the sound
  11347.       is.  The following list of numbers can be used as a reference for
  11348.       nFREQUENCY.  Though the list does not contain all possible frequencies,
  11349.       it should get you started and allow experimentation:
  11350.  
  11351.        247   B
  11352.        262   C
  11353.        277   C# (# = sharp)
  11354.        294   D
  11355.        311   D#
  11356.        330   E
  11357.        349   F
  11358.        370   F#
  11359.        392   G
  11360.        415   G#
  11361.        440   A
  11362.        466   A#
  11363.        494   B
  11364.        523   Middle C
  11365.        554   C#
  11366.        587   D
  11367.        622   D#
  11368.        659   E
  11369.        698   F
  11370.        740   F#
  11371.        784   G
  11372.        880   A
  11373.        988   B
  11374.        1046  C
  11375.        1175  D
  11376.        1319  E
  11377.        1397  F
  11378.        1568  G
  11379.        1760  A
  11380.        1976  B
  11381.  
  11382.      SEE ALSO
  11383.  
  11384.       ALARM, BEEP
  11385.  
  11386.  
  11387.  
  11388.  
  11389.      Intellicomm v2.01               SCRIPT.DOC                            179
  11390.      
  11391.      
  11392.  
  11393.      EXAMPLE
  11394.  
  11395.        TONE 440 10      ;A
  11396.        delaync 1        ;staccato (distinctive notes that don't blend)
  11397.        TONE 494 10      ;B
  11398.        delaync 1
  11399.        TONE 523 10      ;C
  11400.  
  11401.      TXFLUSH__________________________________________________________________
  11402.  
  11403.      SUMMARY
  11404.  
  11405.       TXFLUSH
  11406.  
  11407.      DESCRIPTION
  11408.  
  11409.       Clears (flushes) the COM port Transmit Buffer.  Characters sent to the
  11410.       modem using SEND, SENDNC, SENDBIF, etc., are not transmitted
  11411.       immediately: they are placed in a Transmit Buffer until the modem is
  11412.       ready to accept the characters.  Use TXFLUSH to clear this buffer if
  11413.       necessary.
  11414.  
  11415.      SEE ALSO
  11416.  
  11417.       RXFLUSH
  11418.  
  11419.      UPDATEDNDX_______________________________________________________________
  11420.  
  11421.      SUMMARY
  11422.  
  11423.       UPDATEDNDX
  11424.  
  11425.      DESCRIPTION
  11426.  
  11427.       Uploades the DOWNLOAD.NDX (same as selecting Tools | Update DOWNLOAD.NDX
  11428.       from the File Tagger).  'Update' means that all directories the user has
  11429.       defined in the main setup 'DOWNLOAD.NDX Directories' item will be
  11430.       scanned, and all files in these directories that do not exist in the
  11431.       DOWNLOAD.NDX index will be added.  This is how Intellicomm keeps track
  11432.       of files you've downloaded, and 
  11433.  
  11434.       On new files imports and automated downloads, Tagger ignores filenames
  11435.       that exist in the DOWNLOAD.NDX.
  11436.  
  11437.      EXAMPLE
  11438.  
  11439.       waitfor "Begin your download..."
  11440.       download "Z"
  11441.       UPDATEDNDX
  11442.  
  11443.      UPLOAD___________________________________________________________________
  11444.  
  11445.      SUMMARY
  11446.  
  11447.  
  11448.  
  11449.  
  11450.      Intellicomm v2.01               SCRIPT.DOC                            180
  11451.      
  11452.      
  11453.  
  11454.       UPLOAD sPROTOCOL sFILENAME1 [sFILENAME2 ...]
  11455.  
  11456.      DESCRIPTION
  11457.  
  11458.       Uploads sFILENAME1 and [sFILENAME 2 ...] if specified using transfer
  11459.       protocol sPROTOCOL.  sFILENAME1 is required by all protocols and may be
  11460.       a filename (FILENAME.EXT) or an explicit file and path
  11461.       (D:\PATH\FILENAME.EXT).  If a lone filename (no D: or \PATH\) is
  11462.       specified in any of the sFILENAME? parameters, UPLOAD searches:
  11463.  
  11464.       1) The directories on the Upload PATH ($UL_PATH), defined in the main
  11465.          setup or the current BIF.
  11466.       2) The current Download Directory ($DL_DIR), defined in the main setup
  11467.          or the current BIF.
  11468.       3) If *pathsch (main setup item "Use PATH to Locate Files") is non-zero,
  11469.          all directories on the DOS PATH are then searched if the file cannot
  11470.          be found in any of the directories above.
  11471.  
  11472.       Note that sFILENAME1 may also be specified as "@FILELIST", where
  11473.       @FILELIST is a 'list' of files.  The contents of the file 'FILELIST'
  11474.       would contain one or more filenames to upload (again, each file on the
  11475.       list may include a D:\PATH\ if necessary), with each filename or
  11476.       filespec on a separate line.
  11477.  
  11478.       sFILENAME2 and beyond are only supported by the 'batch' protocols below
  11479.       which have an asterisk following their name.  Further, batch protocols
  11480.       accept the DOS wildcard characters * and ? in any of the sFILENAMEn
  11481.       parameters, whether specified explicitly or via a @FILELIST.
  11482.  
  11483.       sPROTOCOL is the 'hotkey' used to select the protocol from the protocol
  11484.       menu from Terminal Mode (including external protocols, if any are
  11485.       installed):
  11486.  
  11487.       "A" = ASCII
  11488.       "R" = Relaxed Xmodem
  11489.       "X" = Xmodem
  11490.       "1" = Xmodem-1K
  11491.       "K" = Xmodem-1K-G
  11492.       "Y" = Ymodem*
  11493.       "G" = Ymodem-G*
  11494.       "Z" = Zmodem*
  11495.  
  11496.       NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols.  This
  11497.       means that they can upload several files using a single UPLOAD command.
  11498.  
  11499.      ERRORLEVEL
  11500.  
  11501.       0  Transfer successful (if batch, all files were uploaded)
  11502.       1  User abort ([Esc] pressed)
  11503.       2  Connection lost
  11504.       3  Remote (BBS protocol) cancelled
  11505.       4  Disk read error
  11506.       5  Bad external protocol (if called an external and not found)
  11507.       6  Flow control error (activated by remote and not deactivated)
  11508.  
  11509.  
  11510.  
  11511.  
  11512.      Intellicomm v2.01               SCRIPT.DOC                            181
  11513.      
  11514.      
  11515.  
  11516.       7  Miscellaneous protocol error (too many timeouts, NAKs, etc).
  11517.  
  11518.      SEE ALSO
  11519.  
  11520.       DOWNLOAD
  11521.  
  11522.      EXAMPLE 1
  11523.       
  11524.       UPLOAD "1" "FILENAME.ZIP" ;Upload FILENAME.ZIP using Xmodem-1K
  11525.  
  11526.      EXAMPLE 2
  11527.  
  11528.        ;Upload D:\FILE1.ZIP, C:\TEMP\FILE2.ZIP and FILE3.ZIP using Ymodem
  11529.  
  11530.       UPLOAD "Y" "D:\FILE1.ZIP" "C:\TEMP\FILE2.ZIP" "FILE3.ZIP"
  11531.  
  11532.      EXAMPLE 3
  11533.  
  11534.        ;Example upload using a file list
  11535.  
  11536.       variable f                ;used to hold the file handle (number)
  11537.       fopen f "UPLIST.$$$" "w"  ;create a file called UPLIST.$$$, "w"rite mode
  11538.       fputs f "\DIR1\FILE1.ZIP" ;fputs writes \DIR1\FILE1.ZIP to the file
  11539.       fputs f "\DIR2\*.*"       ;all files in \DIR2
  11540.       fputs f "\DIR3\FILE?.*"
  11541.        ; ... etc
  11542.       fclose f                  ;close the file (important)
  11543.  
  11544.       UPLOAD "Z" "@UPLIST.$$$"  ;@ tells the protocol to use a file list
  11545.       delete "UPLIST.$$$"       ;delete the list
  11546.  
  11547.      VARIABLE_________________________________________________________________
  11548.  
  11549.      SUMMARY
  11550.  
  11551.       VARIABLE vNAME
  11552.  
  11553.      DESCRIPTION
  11554.  
  11555.       Creates a variable called vNAME.
  11556.  
  11557.      SEE ALSO
  11558.  
  11559.       SCRTUTOR.DOC explains variables in detail.
  11560.  
  11561.      EXAMPLE
  11562.  
  11563.       VARIABLE my_variable
  11564.  
  11565.      VPUSH____________________________________________________________________
  11566.  
  11567.      SUMMARY
  11568.  
  11569.       VPUSH [nX1] [nY1] [nX2] [nY2]
  11570.  
  11571.  
  11572.  
  11573.  
  11574.      Intellicomm v2.01               SCRIPT.DOC                            182
  11575.      
  11576.      
  11577.  
  11578.      DESCRIPTION
  11579.  
  11580.       Saves screen data (including colors) to an internal memory buffer for
  11581.       later restoration with VPOP.  The parameters following VPUSH are
  11582.       optional screen coordinates which allow you to save a portion of the
  11583.       screen instead of saving the entire screen (the square brackets denote
  11584.       optional items; you must not use square brackets when specifying the
  11585.       parameters).  nX1 is the top screen column (left to right) nY1 is the
  11586.       top screen row (top to bottom) nX2 is the ending screen colum and nY2 is
  11587.       the ending screen row.  
  11588.  
  11589.       If you omit one or more of the screen coordinates, the screen limit is
  11590.       assumed.  The limits for nX1, nY1 are 1, 1 (top screen corner) and the
  11591.       limits for nX2, nY2 are $SCRN_WIDTH, $SCRN_HEIGHT (System Variables
  11592.       which hold the current width and height of the screen).  VPUSH does NOT
  11593.       observe the screen limits set by the WNDOPEN or WINDOW commands.  No
  11594.       matter what the current WNDOPEN/WINDOW limits are, 1, 1 is always the
  11595.       TOP of the screen to VPUSH and $SCRN_WIDTH, $SCRN_HEIGHT (the total
  11596.       screen witdh and height) are the bottom of the screen.
  11597.  
  11598.       You may VPUSH up to sixteen (16) screens/portions of the screen with
  11599.       multiple VPUSH commands.  To restore the screen data saved by the last
  11600.       VPUSH, use VPOP.
  11601.  
  11602.      ERRORLEVEL
  11603.  
  11604.       0  Screen data saved.
  11605.       1  Not enough memory was available to save the screen data.  VPUSH must
  11606.          allocate 2 bytes of memory per screen character (one for the screen
  11607.          character, and one for the color), so if you save an 80 x 25 screen
  11608.          4200 bytes of memory (about 4K) is required to save the data.
  11609.  
  11610.      SEE ALSO
  11611.  
  11612.       VPOP, WNDOPEN
  11613.  
  11614.      EXAMPLE
  11615.  
  11616.       VPUSH                               ;save the whole screen
  11617.       if $ERRORLEVEL = 1 goto no_memory   ;if $ERRORLEVEL is equal to 1
  11618.       cls
  11619.       pause "The screen was saved before clearing.  Press a key to restore: "
  11620.       VPOP                                ;restore the screen
  11621.  
  11622.       VPUSH 10 10 70 16  ;save from 10,10 to 70,16
  11623.       if $ERRORLEVEL = 1 goto no_memory
  11624.       box "Box Title" 10 10 70 16
  11625.       printraw -1 -1 $NORM_COLOR "This text is centered on the screen in a
  11626.      box"
  11627.       pause
  11628.       VPOP
  11629.       return
  11630.  
  11631.      no_memory:
  11632.  
  11633.  
  11634.  
  11635.  
  11636.      Intellicomm v2.01               SCRIPT.DOC                            183
  11637.      
  11638.      
  11639.  
  11640.       print "Not enough memory was available to save screen data."
  11641.       pause "Please press a key... "
  11642.       exit
  11643.  
  11644.      VGETCHR__________________________________________________________________
  11645.  
  11646.      SUMMARY
  11647.  
  11648.       VGETCHR vBUFFER
  11649.  
  11650.      DESCRIPTION
  11651.  
  11652.  
  11653.       Gets the character at the current cursor position, and stores it in
  11654.       vBUFFER.  Color information is ignored.
  11655.  
  11656.      SEE ALSO
  11657.  
  11658.       VGETCHRS
  11659.  
  11660.      EXAMPLE
  11661.  
  11662.       variable c
  11663.  
  11664.       VGETCHR c
  11665.  
  11666.       print "The character at the current cursor position is '" c "'"
  11667.  
  11668.      VGETCHRS_________________________________________________________________
  11669.  
  11670.      SUMMARY
  11671.  
  11672.       VGETCHRS vBUFFER nSCRN_X nSCRN_Y nNUMCHARS
  11673.  
  11674.      DESCRIPTION
  11675.  
  11676.       Gets nNUMCHARS characters from the video screen at nSCRN_X (x coordinate
  11677.       left to right) nSCRN_Y (y coordinate top to bottom) and stores the
  11678.       characters in vBUFFER.  Screen color information is ignored.
  11679.  
  11680.       The screen coordinates nSCRN_X and nSCRN_Y are NOT relative to the
  11681.       current screen WINDOW: coordinates 1 1 are always the top left corner of
  11682.       the screen.  Coordinates $SCRN_WIDTH $SCRN_HEIGHT (the current width and
  11683.       height of the screen; normally 80 25 or 80 rows by 25 columns) are the
  11684.       bottom right corner of the screen.  This allows VGETCHRS to read video
  11685.       characters that are outside the screen WINDOW, such as characters on the
  11686.       Icom status line.
  11687.  
  11688.       VGETCHRS is mainly of use after a WAITFOR.  For example if you wanted to
  11689.       check the remaining online time in a BBS prompt you could wait for the
  11690.       prompt then use VGETCHRS to get the online time from wherever it shows
  11691.       up on the prompt.  See example 1 below.
  11692.  
  11693.  
  11694.  
  11695.  
  11696.      Intellicomm v2.01               SCRIPT.DOC                            184
  11697.      
  11698.      
  11699.  
  11700.      SEE ALSO
  11701.  
  11702.       VGETCHR
  11703.  
  11704.      EXAMPLE 1
  11705.  
  11706.       ;This example gets the remaining online time from a BBS prompt.
  11707.       ; Different types of BBS software display the online time in
  11708.       ; different positions (or not at all) so any scripts you write
  11709.       ; along these lines will be reliant on a specific BBS or door type.
  11710.       ;
  11711.       ; For the example a standard PCBoard Main Menu prompt is assumed:
  11712.       ;
  11713.       ;(XXX min. left) Main Board Command?
  11714.  
  11715.       variable time_left
  11716.  
  11717.       waitfor "Command?"              ;assumes not at the prompt yet... if
  11718.                                       ; the script is already AT the prompt
  11719.                                       ; this WAITFOR is unnecessary
  11720.       vgetchrs time_left 2 $SCRN_Y 3  ;column 2, current row, 3 characters
  11721.       add time_left time_left 0       ;this math operation, while it does
  11722.                                       ; nothing (adds zero) will get rid of
  11723.      any
  11724.                                       ; spaces or text.  Also if the
  11725.                                       ; characters VGETCHRS got were not
  11726.                                       ; numbers at all, time_left will be
  11727.                                       ; equal to 0 (zero) after the math
  11728.                                       ; operation
  11729.       if time_left = 0 goto have_time ;Impossible, or we wouldn't be online.
  11730.                                       ; More than likely the BBS uses
  11731.      different
  11732.                                       ; prompt format.  If this occurs your
  11733.                                       ; script might just assume that there
  11734.                                       ; is ample online time.
  11735.       if time_left > 30 goto have_time ;more than 30 minutes available
  11736.  
  11737.         ;less than 30 minutes is available... exit the script, logoff, hangup,
  11738.  
  11739.         ; whatever would suit the occasion
  11740.       exit
  11741.  
  11742.      have_time:
  11743.         ;30 minutes or more is available... do whatever you needed more than
  11744.         ; 30 minutes to do
  11745.        send "D SOMEFILE.ZIP Z"
  11746.        waitfor "(Ctrl-X)"
  11747.        download "Z"
  11748.        exit
  11749.  
  11750.      EXAMPLE 2
  11751.  
  11752.       variable BBS
  11753.       variable H
  11754.  
  11755.  
  11756.  
  11757.  
  11758.      Intellicomm v2.01               SCRIPT.DOC                            185
  11759.      
  11760.      
  11761.  
  11762.       variable M
  11763.       variable old_stat $STAT_ON  ;save status line state (on/off)
  11764.  
  11765.        ;Status line reference for example; numeric ruler shows the nSCRN_X
  11766.        ; coordinates of items on the status line
  11767.  
  11768.        ; Joe's BBS            HH:MM | Script|  19200 N81| ICOM.CAP     | ...
  11769.        ;1234567890123456789012345678901234567890123456789012345678901234 ...
  11770.        ;         1         2         3         4         5         6
  11771.  
  11772.       offline return                     ;skip if not online
  11773.       assign $STAT_ON 1                  ;make sure status line is on
  11774.       vgetchrs BBS 2 $SCRN_HEIGHT 20     ;Get 20 characters from column 2
  11775.       vgetchrs H 23 $SCRN_HEIGHT 2       ;Get 2 characters from column 23
  11776.       vgetchrs M 26 $SCRN_HEIGHT 2       ;Get 2 characters from column 26
  11777.       assign $STAT_ON old_stat           ;put it back the way it was (if off)
  11778.  
  11779.       msgopen "Connected to " BBS " for " H " hours and " M " minutes"
  11780.       inkeyw
  11781.       msgclose
  11782.       return
  11783.  
  11784.      VPOP_____________________________________________________________________
  11785.  
  11786.      SUMMARY
  11787.  
  11788.       VPOP
  11789.  
  11790.      DESCRIPTION
  11791.  
  11792.       Restores the last screen saved with VPUSH.
  11793.  
  11794.      SEE ALSO
  11795.  
  11796.       VPUSH
  11797.  
  11798.      EXAMPLE
  11799.  
  11800.  
  11801.       VPUSH
  11802.       cls
  11803.       pause "The screen was saved before it was cleared... Press a key: "
  11804.       VPOP
  11805.  
  11806.      WAITFOR__________________________________________________________________
  11807.  
  11808.      SUMMARY
  11809.  
  11810.       WAITFOR sTEXT [nTIMEOUT] [LABEL]
  11811.  
  11812.      DESCRIPTION
  11813.  
  11814.       WAITFOR pauses a script to wait for specific text from the COM port
  11815.       (modem or BBS) handling any text defined by WHEN commands while waiting
  11816.  
  11817.  
  11818.  
  11819.  
  11820.      Intellicomm v2.01               SCRIPT.DOC                            186
  11821.      
  11822.      
  11823.  
  11824.       (see WHEN below).  sTEXT is the text to wait for, nTIMEOUT is an
  11825.       optional timeout in seconds (stop waiting after timeout), and LABEL is
  11826.       an optional label to GOTO if the text is not found within the timeout
  11827.       period.  
  11828.  
  11829.       NOTE: Only the first twenty characters of sTEXT are tracked by WAITFOR. 
  11830.       The sTEXT specified in a WAITFOR needn't be the 'end' of a BBS prompt,
  11831.       nor need it be a complete BBS prompt.
  11832.  
  11833.       nTIMEOUT is an optional timeout in seconds.  If you specify a timeout,
  11834.       and sTEXT is not found within the timeout period, WAITFOR will either
  11835.       continue at the next script line when the timeout elapses (if LABEL is
  11836.       not specified) or will GOTO the optional LABEL if you specify it.  If no
  11837.       timeout is specified WAITFOR waits indefinitely for the sTEXT.
  11838.  
  11839.       If you do not wish to GOTO a label if sTEXT is not found within the
  11840.       nTIMEOUT timeout, you may omit the LABEL parameter and simply use the
  11841.       $ERRORLEVEL (see below) to determine whether the text was found or not.
  11842.  
  11843.      ERRORLEVEL
  11844.  
  11845.       0  nTEXT was found.
  11846.       1  nTEXT was not found.  This errorlevel can be of use if you do NOT
  11847.          specify a LABEL parameter to jump to.
  11848.  
  11849.      SEE ALSO
  11850.  
  11851.       WHEN
  11852.  
  11853.      EXAMPLE 1
  11854.  
  11855.       WAITFOR "Main Menu?"     ;wait indefinitely for the main menu
  11856.        ;script continues here if/when Main Menu? is found
  11857.  
  11858.      EXAMPLE 2
  11859.  
  11860.       WAITFOR "Main Menu?" 5   ;wait 5 seconds for the main menu
  11861.       if $ERRORLEVEL = 1 gosub locate_position
  11862.  
  11863.        ;demonstrates how to use $ERRORLEVEL to use a command other than
  11864.        ; GOTO if the text is not found (assumes there is a subroutine in
  11865.        ; the script called 'locate_position:'.  See the WHEN command for
  11866.        ; a real example of locating your position on the BBS.
  11867.  
  11868.      EXAMPLE 3
  11869.  
  11870.       when                               ;clear all WHENs
  11871.       when "Name?"     send "James Brown"
  11872.       when "Password?" send "mypassword"
  11873.       WAITFOR "Selection:" 120 NoMenu
  11874.       return
  11875.      NoMenu:
  11876.       hangup
  11877.  
  11878.  
  11879.  
  11880.  
  11881.      Intellicomm v2.01               SCRIPT.DOC                            187
  11882.      
  11883.      
  11884.  
  11885.        ;waits 2 minutes (120 seconds) for the prompt 'Selection:', handling
  11886.        ; a short logon with WHENs while waiting.  If the Selection: prompt
  11887.        ; is found, the script returns (exits back to terminal mode).  If
  11888.        ; the Selection: prompt is not found within 2 minutes, the script
  11889.        ; hangs up.
  11890.  
  11891.      WAITUNTIL________________________________________________________________
  11892.  
  11893.      SUMMARY
  11894.  
  11895.       WAITUNTIL sTIME [sDAY]
  11896.  
  11897.      DESCRIPTION
  11898.  
  11899.       Displays a box menu allowing the user limited control, then pauses
  11900.       script execution until sTIME on sDAY.  If sDAY is omitted, the day of
  11901.       the week is ignored and only sTIME applies.
  11902.  
  11903.       sTIME can be specified in military time (13:00 = 1:00pm) or am/pm time
  11904.       (1:00p = 13:00).
  11905.  
  11906.       sDAY, if specified can be "Anyday", "Sunday", "Monday", "Tuesday",
  11907.       "Wednesday", "Thursday", "Friday" or "Saturday" or a three letter
  11908.       abbreviation ("Sun", "Mon", etc).
  11909.  
  11910.      ERRORLEVEL
  11911.  
  11912.       None.  The box menu displayed during a WAITUNTIL allows the user to
  11913.       abort the script.  If 'Cancel' is selected by the user, the script
  11914.       simply ends.
  11915.  
  11916.      EXAMPLE
  11917.  
  11918.       WAITUNTIL "12:05a" "Sun"   ;wait until Saturday night at 12:05 am.
  11919.                                  ; [technically Sunday morning... this
  11920.                                  ; is pointed out because people rarely
  11921.                                  ; think of 12:05am SATURDAY as being
  11922.                                  ; Sunday morning, but it is to WAITUNTIL
  11923.                                  ; and your computer]
  11924.  
  11925.      WHEN_____________________________________________________________________
  11926.  
  11927.      SUMMARY
  11928.  
  11929.       WHEN [sTEXT] [cCOMMAND]
  11930.  
  11931.      DESCRIPTION
  11932.  
  11933.       WHEN defines BBS text to watch for (nTEXT) and a command to execute
  11934.       (cCOMMAND) if/when the text is found during a WAITFOR.  Up to nineteen
  11935.       WHENs can be specified prior to a WAITFOR, to handle up to nineteen
  11936.       different BBS prompts while waiting.
  11937.  
  11938.       Note that sTEXT and cCOMMAND are specified as optional parameters above:
  11939.  
  11940.  
  11941.  
  11942.  
  11943.      Intellicomm v2.01               SCRIPT.DOC                            188
  11944.      
  11945.      
  11946.  
  11947.       if you omit both parameters all previously defined WHENs (if any) are
  11948.       cleared.
  11949.  
  11950.       NOTE: Only the first twenty characters of sTEXT are tracked.  If you
  11951.       specify more than twenty characters, WHEN ignores the extra characters. 
  11952.       sTEXT needn't be the 'end' of a BBS prompt, nor need it be a complete
  11953.       BBS prompt.  You 'could' do this:
  11954.  
  11955.        WHEN "!" SEND "something"
  11956.  
  11957.       and Icom would SEND "something" every time an exclamation mark was found
  11958.       during a WAITFOR.  The trick is to define enough of the BBS prompt that
  11959.       it doesn't conflict with other regular text from the BBS.... the above
  11960.       probably wouldn't be a good idea since exclamation marks can show up
  11961.       just about anywhere.  And the reason most of the WHEN examples use the
  11962.       END of the BBS prompt as opposed to the beginning is that the command
  11963.       (normally SEND, to send a response to the prompt) is executed
  11964.       *immediately* after the text is found.  If the BBS has some sort of
  11965.       "keyboard buffer flusher" to erase line noise after displaying prompts,
  11966.       your response to the prompt could be lost if it's sent prematurely.  By
  11967.       defining the end of the BBS prompt in WHENs, including the trailing
  11968.       space on the prompt, you can be fairly sure that the BBS has flushed its
  11969.       input buffer already and won't erase your response.  Further, there is
  11970.       usually some sort of punctuation at the END of a prompt (a question mark
  11971.       or colon or the like) which also helps to make the text "unique".  For
  11972.       example, PCBoard asks for your password using the following prompt:
  11973.  
  11974.       Password (Dots will echo)? 
  11975.  
  11976.       You 'could' get away with using:
  11977.  
  11978.        WHEN "password" send $PASSWORD
  11979.  
  11980.       But this has been done many times (in both BIFs and scripts), and has
  11981.       failed many times when the Sysop has an opening bulletin/news file that
  11982.       has the word "password" in it!  On the other hand, if you use the END of
  11983.       the password prompt:
  11984.  
  11985.       WHEN "(Dots will echo)? " SEND $PASSWORD
  11986.  
  11987.       ...it's VERY unlikely that such text would show up anywhere else but at
  11988.       the password prompt, which is the only place you want your password
  11989.       sent.  The same applies to the BBS prompts you define in your BIFs.
  11990.  
  11991.       The easiest way to use WHEN is with a SEND or GOTO command.  If you want
  11992.       ease of use, SEND/GOTO commands in WHENs are the most straightforward
  11993.       route to go.  SEND simply sends the response to the prompt defined by
  11994.       the WHEN, and GOTO cancels the WAITFOR and jumps to another area of the
  11995.       script.  If you want more power and flexibility, and want to use GOSUBs
  11996.       and other commands in WHENs, read on.
  11997.  
  11998.       If you're handling complicated tasks with GOSUBs in WHEN commands, it's
  11999.       important to understand that you have nineteen WHENs to work with in
  12000.       TOTAL.  Going to a subroutine, or even calling another script, does NOT
  12001.  
  12002.  
  12003.  
  12004.  
  12005.      Intellicomm v2.01               SCRIPT.DOC                            189
  12006.      
  12007.      
  12008.  
  12009.       give you another nineteen WHENs to work with.  If you call WHEN more
  12010.       than nineteen times before clearing previous prompts with a lone WHEN
  12011.       comand, the first WHEN you defined is overwritten.  I.e. it wraps around
  12012.       back to the beginning if you go past nineteen.
  12013.  
  12014.       As long as you understand this (Icom deals with the same limitation in
  12015.       its own automated routines which use the exact same routines WHEN uses)
  12016.       it's really a simple matter to use GOTOs instead of GOSUBs, clear all
  12017.       the WHENs in your subroutine/goto, then jump back up to re-define the
  12018.       original WHENs.  Example:
  12019.  
  12020.      redefine_whens:                 ;label to get above the WHENs
  12021.        
  12022.        WHEN                          ;clear any existing WHENs
  12023.        WHEN "this" GOTO handle_this  ;GOTO instead of GOSUB/RETURN
  12024.         ...etc. up to 18 more
  12025.        WAITFOR "some text"
  12026.  
  12027.      handle_this:
  12028.        WHEN                          ;clear the previous WHENs, start anew
  12029.        WHEN "that" SEND "cmd"
  12030.         ...etc. up to 18 more
  12031.        WAITFOR "something else"
  12032.  
  12033.        GOTO redefine_whens           ;jump back up to the original when done
  12034.  
  12035.      ERRORLEVEL
  12036.  
  12037.       No errorlevel is set by WHEN, since it doesn't do anything until WAITFOR
  12038.       is active... and WAITFOR sets its own error.  If you specify more than
  12039.       nineteen WHENs, the first WHEN is overwritten with no error.
  12040.  
  12041.      SEE ALSO
  12042.  
  12043.       WAITFOR
  12044.  
  12045.      EXAMPLE
  12046.  
  12047.       Please see above for advanced use, and see the Introduction to Scripts
  12048.       at the beginning of the SCRTUTOR.DOC for basic usage.
  12049.  
  12050.      WHILE____________________________________________________________________
  12051.       BREAK___________________________________________________________________
  12052.       CONTINUE________________________________________________________________
  12053.       ENDWHILE________________________________________________________________
  12054.  
  12055.      SUMMARY
  12056.  
  12057.       WHILE nNUM1 OPERATOR nNUM2    ;a numeric comparison
  12058.        cCOMMAND
  12059.        [cCOMMAND]
  12060.       ENDWHILE
  12061.  
  12062.       WHILE sSTR1 OPERATOR sSTR2    ;OR a string comparison
  12063.  
  12064.  
  12065.  
  12066.  
  12067.      Intellicomm v2.01               SCRIPT.DOC                            190
  12068.      
  12069.      
  12070.  
  12071.        cCOMMAND
  12072.        [cCOMMAND]
  12073.       ENDWHILE
  12074.  
  12075.      DESCRIPTION
  12076.  
  12077.       WHILE/ENDWHILE is much like IF/ENDIF, but where IF/ENDIF execute a set
  12078.       of commands once and only once if a given condition is true, WHILE
  12079.       executes a set of commands over and over again, WHILE a given condition
  12080.       is true.
  12081.  
  12082.  
  12083.       BREAK
  12084.       -----
  12085.       The optional BREAK command is only valid *between* WHILE and ENDWHILE
  12086.       commands.  BREAK forces the script processor to break from the loop
  12087.       (exit the loop and skip to the next command following ENDWHILE).  BREAK
  12088.       is used for conditions that cannot be specified directly in the WHILE
  12089.       command.  For example, you may have several numeric and/or string
  12090.       comparisons to perform in the WHILE loop (using SWITCH or IF, which are
  12091.       valid in WHILE loops).  Instead of having to do this:
  12092.  
  12093.        WHILE i < 10
  12094.         if i2 = 1 goto endloop
  12095.         ...
  12096.        ENDWHILE
  12097.      endloop:
  12098.  
  12099.       ...you'd use a BREAK instead:
  12100.  
  12101.        WHILE i < 10
  12102.         if i2 = 1 BREAK   ;exit loop if i2 is equal to 1
  12103.         ...
  12104.        ENDWHILE
  12105.  
  12106.       The BREAK above does the same thing as the first 'goto endloop' example. 
  12107.       You can get out of a loop either way, but BREAK is considered better
  12108.       programming practice.
  12109.  
  12110.       CONTINUE
  12111.       --------
  12112.       The optional CONTINUE command is only valid *between* WHILE and ENDWHILE
  12113.       commands.  CONTINUE forces the script processor to immediately jump back
  12114.       up to the WHILE statement.  Instead of having to do this:
  12115.  
  12116.      toploop:
  12117.        WHILE i < 10
  12118.         inc i
  12119.         if i2 = 1 goto toploop
  12120.         ...
  12121.        ENDWHILE
  12122.  
  12123.       ...you'd use a CONTINUE instead:
  12124.  
  12125.  
  12126.  
  12127.  
  12128.      Intellicomm v2.01               SCRIPT.DOC                            191
  12129.      
  12130.      
  12131.  
  12132.        WHILE i < 10
  12133.         inc i
  12134.         if i2 = 1 CONTINUE
  12135.         ...
  12136.        ENDWHILE
  12137.  
  12138.       The CONTINUE above does the same thing as the first 'goto toploop'
  12139.       example.  You can get back to the top of a loop either way, but CONTINUE
  12140.       is considered better programming practice.  One thing to watch when you
  12141.       use CONTINUE, however, is that you make sure that your WHILE condition
  12142.       or variable is modified BEFORE you use the CONTINUE command.  If you did
  12143.       this:
  12144.  
  12145.        WHILE i < 10
  12146.         if i2 = 1 CONTINUE
  12147.         inc i               ;don't increment 'i' AFTER the CONTINUE
  12148.         ...
  12149.        ENDWHILE
  12150.  
  12151.       and 'i2' was equal to 1 ... your script would hang, since variable 'i'
  12152.       would never be incremented, and thus 'i' would always be less than 10 (i
  12153.       < 10).  Take care of your WHILE variables (INCrementing, DECrementing,
  12154.       assigning values to strings, etc) immediately following the WHILE
  12155.       command at the *top* of the loop rather than at the bottom near the
  12156.       ENDWHILE, and you won't have any problems with CONTINUE.  Try to get
  12157.       into the habit of typing your WHILE loops like this:
  12158.  
  12159.        while somevariable > 1   ;or whatever the condition is
  12160.         dec somevariable        ;put your primary modifier in at the top, just
  12161.                                 ; after you define your WHILE condition
  12162.        endwhile                 ;and add the ENDWHILE so you don't forget it
  12163.  
  12164.       ...and AFTER you have the WHILE/ENDWHILE and your key modifier set up,
  12165.       THEN go and fill the rest of the loop in between (between WHILE and DEC
  12166.       in the example above).
  12167.  
  12168.      ERRORLEVEL
  12169.  
  12170.       WHILE/BREAK/CONTINUE/ENDWHILE do not change $ERRORLEVEL.
  12171.  
  12172.      SEE ALSO
  12173.  
  12174.       SWITCH, IF
  12175.  
  12176.      EXAMPLE
  12177.  
  12178.      WINDOW___________________________________________________________________
  12179.  
  12180.      SUMMARY
  12181.  
  12182.       WINDOW [nX1] [nY1] [nX2] [nY2]
  12183.  
  12184.      DESCRIPTION
  12185.  
  12186.  
  12187.  
  12188.  
  12189.      Intellicomm v2.01               SCRIPT.DOC                            192
  12190.      
  12191.      
  12192.  
  12193.       Sets the screen WINDOW.  All text displayed to the screen with PRINT,
  12194.       PRINTNC or PAUSE as well as text received from the communications port,
  12195.       stays within the current WINDOW coordinates.  nX1, nY1 is the top corner
  12196.       of the window (X1 is the screen column, right to left, Y1 is the screen
  12197.       row top to bottom) while nX2, nY2 is the bottom corner.  If no screen
  12198.       coordinates follow WINDOW the window is set to the full screen.
  12199.  
  12200.      SEE ALSO
  12201.  
  12202.       WNDOPEN, WNDCLOSE
  12203.  
  12204.      EXAMPLE
  12205.  
  12206.       cls
  12207.       WINDOW 5 5 75 20  ;leaves 4 rows/columns around the Window on all sides
  12208.  
  12209.      WNDCLOSE_________________________________________________________________
  12210.  
  12211.      SUMMARY
  12212.  
  12213.       WNDCLOSE
  12214.  
  12215.      DESCRIPTION
  12216.  
  12217.       Closes the last window opened with the WNDOPEN command (restores the
  12218.       previous contents of the video screen), restores the previous
  12219.       $SCRN_COLOR, cursor on/off status, and cursor coordinates.  Basically
  12220.       puts everything back the way it was before the last WNDOPEN command.
  12221.  
  12222.      SEE ALSO
  12223.  
  12224.       WNDOPEN
  12225.  
  12226.      EXAMPLE
  12227.  
  12228.       wndopen "Courtesy of WNDOPEN"
  12229.       pause "Press a key to remove this window...
  12230.       WNDCLOSE
  12231.  
  12232.      WNDOPEN__________________________________________________________________
  12233.  
  12234.      SUMMARY
  12235.  
  12236.       WNDOPEN [sTITLE] [nX1] [nY1] [nX2] [nY2]
  12237.  
  12238.      DESCRIPTION
  12239.  
  12240.       WNDOPEN first saves the screen area of the window you're opening (given
  12241.       screen X1, Y1, X2, Y2 coordinates), saves the current WINDOW
  12242.       coordinates, screen color and cursor x,y position, then uses BOX to
  12243.       display a window box with optional title, then uses the WINDOW command
  12244.       to set the current WINDOW within the box, then calls GOTOXY 1 1 to move
  12245.       the cursor to the top of the window.  The process is reversed when
  12246.       WNDCLOSE is called.
  12247.  
  12248.  
  12249.  
  12250.  
  12251.      Intellicomm v2.01               SCRIPT.DOC                            193
  12252.      
  12253.      
  12254.  
  12255.       You can call WNDOPEN up to 16 times (open 16 different windows,
  12256.       overlapping or hiding previous windows) before calling WNDCLOSE.
  12257.  
  12258.       sTITLE is an optional title to display in the window border top left
  12259.       corner.
  12260.  
  12261.       nX1 nY1 specify the top left corner of the window, nX2 nY2 specify the
  12262.       bottom right corner of the window.  [X is a screen column left to right,
  12263.       Y is a screen row top to bottom.]  If nX1 or nY1 is omitted, 1 is
  12264.       assumed (top corner).  If nX2 is omitted, $SCRN_WIDTH is assumed.  If
  12265.       nY2 is omitted, $SCRN_HEIGHT is assumed.
  12266.  
  12267.      SEE ALSO
  12268.  
  12269.       BOX, WNDCLOSE
  12270.  
  12271.      EXAMPLE
  12272.  
  12273.       ;Please see SCRDEMO.SCR for a more detailed example of WNDOPEN/WNDCLOSE
  12274.  
  12275.       WNDOPEN "Courtesy of WNDOPEN"
  12276.       pause "Press a key to remove this window...
  12277.       wndclose
  12278.       
  12279.      XOR______________________________________________________________________
  12280.  
  12281.      SUMMARY
  12282.  
  12283.       XOR vRESULT nNUM nBITMASK
  12284.  
  12285.      DESCRIPTION
  12286.  
  12287.       Performs a bitwise eXclusive OR on nNUM using nBITMASK and stores the
  12288.       result in variable vRESULT.  Exclusive OR gets right down to the nitty
  12289.       grittys of how computers store numbers.  You must understand the binary
  12290.       number system to understand XOR totally -- but you still can make use of
  12291.       it without understanding binary by simply following this tip:  The exact
  12292.       same XOR can change a 1 to a 0, and a 0 to a 1.  Why would you care
  12293.       about such things?  Well, it's an effecient and simple way to handle
  12294.       "toggles".  If you want something to toggle itself on or off, you simply
  12295.       do an
  12296.  
  12297.        XOR someflag someflag 1
  12298.  
  12299.       on the variable (where 'someflag' is the variable you want to toggle),
  12300.       and it'll toggle the value of the variable to on or off (1 or 0)
  12301.       depending upon its current value.
  12302.  
  12303.       You can actually store many toggles in a single variable... since there
  12304.       are many bits in binary numbers that can be turned on/off with XOR.  You
  12305.       can toggle each bit on or off using XOR, but unless you know binary well
  12306.       you should stick to "XOR v v 1" (XOR the variable with the number 1) to
  12307.       turn your toggle off or on.
  12308.  
  12309.  
  12310.  
  12311.  
  12312.      Intellicomm v2.01               SCRIPT.DOC                            194
  12313.      
  12314.      
  12315.  
  12316.      SEE ALSO
  12317.  
  12318.       AND, OR, SHL, SHR
  12319.  
  12320.      EXAMPLE
  12321.  
  12322.        variable mytoggle          ;declare the toggle (starts at 0 by default)
  12323.  
  12324.        gosub switch_toggle        ;sets 'mytoggle' to 1
  12325.        gosub switch_toggle        ;sets 'mytoggle' to 0
  12326.        gosub switch_toggle        ;sets it back to 1 
  12327.        return
  12328.  
  12329.      switch_toggle:
  12330.        XOR mytoggle mytoggle 1    ;changes 1 to 0, or 0 to 1
  12331.        return
  12332.  
  12333.  
  12334.  
  12335.  
  12336.      Intellicomm v2.01               SCRIPT.DOC                            195
  12337.      
  12338.      
  12339.  
  12340.                                      APPENDIXES
  12341.  
  12342.  
  12343.                                 A.  SYSTEM VARIABLES
  12344.  
  12345.      A.1  Introduction
  12346.  
  12347.      System Variables can be used in place of constant parameters with any
  12348.      script command that takes a parameter.  They're used to increase
  12349.      flexibility in your scripts, to allow you to write scripts that can be
  12350.      used by others, and also to allow you to write scripts that will adapt to
  12351.      changes you make to your OWN Intellicomm setup in the future.
  12352.  
  12353.      If you write a script that does some work in your 'Message Directory',
  12354.      and you specify your existing message directory into your script (using a
  12355.      constant such as "C:\MYMSGDIR") to refer to the directory, then your
  12356.      script will fail if you later rename that directory and define a new one
  12357.      in the Icom main setup or BIF.  By using the $MSG_DIR System Variable in
  12358.      your script, instead of specifying the value as a constant, the script
  12359.      adapts to changes when you make them.
  12360.  
  12361.      When you use a System Variable in a script command, it's up to you to
  12362.      make sure that the variable has some relevance to the parameter.  If you
  12363.      try this:
  12364.  
  12365.      PRINTRAW $BAR_COLOR $BORDER_COLOR $BOLD_COLOR "Print this text"
  12366.  
  12367.      it won't make much sense; though you CAN get away with it if you try
  12368.      (PRINTRAW expects the first parm to be a screen column, the second to be
  12369.      a screen row, and only the THIRD parm to be a color).  It would make more
  12370.      sense to use this:
  12371.  
  12372.      PRINTRAW $SCRN_X $SCRN_Y $TERM_COLOR "Print this text"
  12373.  
  12374.      No checks are made to ensure that you're using the "proper" System
  12375.      Variable for a given case, since there really is no such thing as using
  12376.      the "proper" variable for a given case.  The whole idea behind scripts is
  12377.      to allow you to do the unexpected and expand the horizons.
  12378.  
  12379.      A.1.1  BIF and INI (main setup) Variables 
  12380.  
  12381.      The System Variables outlined in this section do not cover all of the
  12382.      Icom system information available to you from a script: they cover only
  12383.      the most commonly used system information.  You can access ANY Icom
  12384.      variables using BIF Variables, and Main Setup Variables.  See the next
  12385.      two appendices below.
  12386.  
  12387.      A.1.2  Changing System Variables
  12388.  
  12389.      Do not CHANGE the value of any important system variables ($SCRN_X and
  12390.      $SCRN_Y are not considered important, unless the BBS is trying to display
  12391.      something on-screen at the time) unless you're sure about what you're
  12392.      doing.  Many of the system variables are made available for informational
  12393.      purposes, and are not meant to be changed ($HOME_DIR, for example, cannot
  12394.  
  12395.  
  12396.  
  12397.  
  12398.      Intellicomm v2.01               SCRIPT.DOC                            196
  12399.      
  12400.      
  12401.  
  12402.      be changed, nor can $DATE or $TIME or some of the other variables that
  12403.      simply return information).  The various COLOR variables and PROTOCOL /
  12404.      DIRECTORY variables can be changed, though if you change any of them in a
  12405.      script you change them globally (the new information is used everywhere
  12406.      in Intellicomm) for the duration of the Icom session; until Icom is
  12407.      removed from memory and re-loaded, or until another main setup file (or
  12408.      BIF, for some variables) is loaded.
  12409.  
  12410.      You can cause Intellicomm to malfunction by changing the contents of some
  12411.      of these System Variables, if you don't do it properly and if you don't
  12412.      restore the original value before your script ends.  If you DO change any
  12413.      important variables in your scripts, make sure that you save the contents
  12414.      of the variable before changing it, then restore the contents when your
  12415.      script ends.  Example:
  12416.  
  12417.       variable old_dl_dir $DL_DIR   ;define 'old_dl_dir', put contents of
  12418.                                     ; original $DL_DIR variable in it.
  12419.       assign $DL_DIR "C:\MYDIR"     ;change the Download Dir to a new
  12420.      directory
  12421.       ...                           ;main body of script here
  12422.       exit_script:                  ;a label you GOTO to exit the script
  12423.        assign $DL_DIR old_dl_dir
  12424.        exit
  12425.  
  12426.      A.1.3  READ ONLY System Variables
  12427.  
  12428.      To avoid problems in your scripts (and with Intellicomm in general) that
  12429.      may be very difficult to locate, some of the System Variables are read
  12430.      only.  If you try to modify the value of these variables directly your
  12431.      script will abort with a "$VARIABLE_NAME is READ ONLY" error.  If a
  12432.      variable is read only, then you can access the contents of the variable
  12433.      for informational purposes:
  12434.  
  12435.       variable myfile $HOME_DIR "MYFILE.EXT
  12436.  
  12437.        ;Using this, you'd end up with something like:
  12438.        ; C:\ICOM\MYFILE.EXT in 'myfile'.  $HOME_DIR is the directory
  12439.        ; that ICOM.EXE is located in.
  12440.  
  12441.      But you cannot change the variable itself:
  12442.  
  12443.       assign $HOME_DIR "C:\SOMEDIR\"
  12444.  
  12445.      Some of the system directories CAN be changed, however.  If you change
  12446.      any of the System Variables that specify directories ($MSG_DIR, $REP_DIR,
  12447.      etc) then Icom will add a slash to the end of the directory name if you
  12448.      forget to specify it in your script.  ALL directory names must have a
  12449.      trailing slash, since Icom simply appends filenames to the directory when
  12450.      it needs a file from a given directory.  You don't want this: 
  12451.      C:\MYDIRMYFILE.EXT.  You want this: C:\MYDIR\MYFILE.EXT.  Thus all
  12452.      directories have a trailing slash in MEMORY.  Sometimes directories are
  12453.      displayed without the trailing slash, and sometimes they're DEFINED
  12454.      without a trailing slash in the main setup/BIFs, but Icom automatically
  12455.      adds the slash when storing the variable in memory.  EXCEPTION:  The
  12456.  
  12457.  
  12458.  
  12459.  
  12460.      Intellicomm v2.01               SCRIPT.DOC                            197
  12461.      
  12462.      
  12463.  
  12464.      $UL_PATH (Upload PATH) System Variable simply contains a list of
  12465.      directories that Icom uses to locate files to upload, and these
  12466.      directories need not have a trailing slash (slashes are added when
  12467.      needed).
  12468.  
  12469.      A.2  System Variable Summary
  12470.  
  12471.      All System Variables are listed in alphabetical order below, with the
  12472.      variable name first, a description of the variable, then any special
  12473.      notes/warnings about using the variable.  To see a quick listing of
  12474.      System Variables grouped by TOPIC, see the COMMANDS AT A GLANCE section.
  12475.  
  12476.      The COLOR variables contain a number that specifies both the foreground
  12477.      and background color.  To create your own colors (to create custom
  12478.      foreground or background colors), see the COLOR CODES Appendix below.  
  12479.  
  12480.  
  12481.      $ALARMS__________________________________________________________________
  12482.  
  12483.       Determines whether alarms are heard.  Intellicomm sounds an alarm after
  12484.       connecting and when file transfers complete.  Also determines whether
  12485.       script ALARM commands are heard.
  12486.  
  12487.      $BAR_COLOR_______________________________________________________________
  12488.  
  12489.       The color of menu hilight bars (currently hilighted item).
  12490.  
  12491.      $BBS_AREA________________________________________________________________
  12492.  
  12493.       Read only.  Of use only when you call a script via a job Custom
  12494.       Command/Run Script task, $BBS_AREA allows you to check which area of the
  12495.       BBS your script is located, when Icom turns control over:
  12496.  
  12497.        [L] = the BBS Main Menu
  12498.        [M] = the BBS Message Menu
  12499.        [F] = the BBS File Menu
  12500.        [B] = the BBS Time Bank Menu
  12501.  
  12502.       The information is presented in this format (between square brackets) to
  12503.       maintain compatibility with the NEWAREA command.  See NEWAREA for
  12504.       details.
  12505.  
  12506.      $BETA_VERSION____________________________________________________________
  12507.  
  12508.       The current beta version of Intellicomm (0 if a production release).
  12509.  
  12510.      $BIF_DIR_________________________________________________________________
  12511.  
  12512.       The BIF Directory (where .BIF files are stored).
  12513.  
  12514.      $BIF_NAME________________________________________________________________
  12515.  
  12516.       The name of the currently loaded BIF.
  12517.  
  12518.  
  12519.  
  12520.  
  12521.      Intellicomm v2.01               SCRIPT.DOC                            198
  12522.      
  12523.      
  12524.  
  12525.      $BOLD_COLOR______________________________________________________________
  12526.  
  12527.       The standard bold text color.  Used to hilight menu hotkeys, and to
  12528.       emphasize important information.  The PRINT, PRINTNC, and PAUSE commands
  12529.       allow you to use $BOLD_COLOR by specifying ^B (Ctrl-B) in your print
  12530.       strings.  Example: PRINT "This is normal.  ^BThis is bold.^B"
  12531.  
  12532.      $BORDER_COLOR____________________________________________________________
  12533.  
  12534.       The color of menu and box borders.  Used by Intellicomm for all menus,
  12535.       boxes, etc., and also by the WNDOPEN, MSGWIND, MSGOPEN commands.
  12536.  
  12537.      $BSSWAP__________________________________________________________________
  12538.  
  12539.       If set to zero, the backspace key sends a backspace character.  If non-
  12540.       zero, the backspace key sends a DEL character.
  12541.  
  12542.      $CAP_NAME________________________________________________________________
  12543.  
  12544.       The full D:\PATH\FILENAME.EXT of the capture log.
  12545.  
  12546.      $CAP_STAT________________________________________________________________
  12547.  
  12548.       Read Only.  This variable can only be changed by Icom (when it
  12549.       opens/closes the capture file), the user ([Alt-L] terminal key), or
  12550.       CAPTURE, CAPPAUSE, CAPCLOSE in a script.
  12551.  
  12552.      $CAREA_FLD_______________________________________________________________
  12553.  
  12554.       The File Area of the currently loaded Tagger catalog record (CGETREC). 
  12555.       Use NEWAREA $CAREA_FLD to change to the proper BBS file area to download
  12556.       the file.
  12557.  
  12558.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12559.       on using the $Cxxxx_FLD variables.
  12560.  
  12561.      $CARRIER_________________________________________________________________
  12562.  
  12563.       Reflects the state of the DCD signal (carrier detect) on the current
  12564.       $COM_PORT.  If 0 (zero), the modem is reporting that it is offline (not
  12565.       connected).  If non-zero the modem is reporting that is is online
  12566.       (connected).
  12567.  
  12568.       Unfortunately most modems do NOT report the carrier status properly when
  12569.       using the factory (default) settings.  If your modem is reporting online
  12570.       all the time ($CARRIER <> 0 even when offline), the fix will be either
  12571.       adding an &C1 command to your Initialize Modem string in the Icom main
  12572.       setup (2400 baud modems and faster) or the flipping of a small switch on
  12573.       or inside the modem; usually switch #6 (1200 bauders and below).  See
  12574.       "Common Questions & Answers" in the Icom online help for more
  12575.       information.
  12576.  
  12577.      $CAT_DIR_________________________________________________________________
  12578.  
  12579.  
  12580.  
  12581.  
  12582.      Intellicomm v2.01               SCRIPT.DOC                            199
  12583.      
  12584.      
  12585.  
  12586.       The Catalog Directory, where Tagger catalogs are stored.
  12587.  
  12588.      $CAT_NAME________________________________________________________________
  12589.  
  12590.       The name of the currently open Tagger catalog (if any).
  12591.  
  12592.      $CCDATE_FLD______________________________________________________________
  12593.  
  12594.       The Catalog Date of the currently loaded Tagger catalog record
  12595.       (CGETREC).  See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for
  12596.       more details on using the $Cxxxx_FLD variables.
  12597.  
  12598.      $CDAY_FLD________________________________________________________________
  12599.  
  12600.       The Transfer Day of the currently loaded Tagger catalog record
  12601.       (CGETREC). 0 = Anyday, 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 =
  12602.       Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.  Use $DOW to check
  12603.       the current day of the week.
  12604.  
  12605.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12606.       on using the $Cxxxx_FLD variables.
  12607.  
  12608.      $CFDATE_FLD______________________________________________________________
  12609.  
  12610.       The File Date of the currently loaded Tagger catalog record (CGETREC) in
  12611.       the format YYYYMMDD.  Use CDATE2DATE to convert these dates to the usual
  12612.       MM/DD/YY style.
  12613.  
  12614.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12615.       on using the $Cxxxx_FLD variables.
  12616.  
  12617.      $CFLAG_FLD_______________________________________________________________
  12618.  
  12619.       The user-defineable 'flags' field for the currently loaded catalog
  12620.       record (CGETREC).  $CFLAG_FLD is a general purpose flag in EACH catalog
  12621.       RECORD, that you can use as you see fit.  The real length of the 'FLAGS'
  12622.       field (a new database field introduced in v2.01) is 5 bytes; you have
  12623.       access to one of these bytes from scripts (using $CFLAG_FLD) for
  12624.       anything you want.  Icom uses the FLAGS field (a portion of it that
  12625.       cannot be accessed from scripts) to keep track of file transfer results
  12626.       and Stubborn Tags.  Each time a filename is sent to the BBS during
  12627.       automated transfers, Icom increments a counter stored in the FLAGS
  12628.       field.  If the counter goes past 3, Icom cancels the transfer (keeping
  12629.       the file tagged), which eliminates any possibility that the same
  12630.       filename will be entered over and over again forever due to bad BIF
  12631.       setup, errors, etc.  When 'File not Found', 'No time', 'No bytes',
  12632.       'Transfer Successful', etc. are received from the BBS, Icom makes
  12633.       another note in the flags field, storing 'C' to cancel the transfer
  12634.       (Untag the file), 'S' for a successful transfer, etc.
  12635.  
  12636.       If you write a script to perform auto downloads, you can put $CFLAG_FLD
  12637.       to the same use.  Icom never touches or checks the contents of
  12638.       $CFLAG_FLD (the portion that scripts have access to) so you can use it
  12639.       as you see fit to keep track of anything that your scripts need to keep
  12640.  
  12641.  
  12642.  
  12643.  
  12644.      Intellicomm v2.01               SCRIPT.DOC                            200
  12645.      
  12646.      
  12647.  
  12648.       track of.  The field is set to a blank space (" ") by default, and it's
  12649.       good practice to set it back that way when your script is done with it. 
  12650.       Example:
  12651.  
  12652.        cgetrec 5
  12653.        assign $CFLAG_FLD "A"  ;"A" would signify some condition to you...
  12654.                               ; maybe that you'd already tried to download
  12655.                               ; the file, or that the record should be
  12656.                               ; deleted or untagged, etc.
  12657.        cputrec
  12658.  
  12659.        Later, to check the flag:
  12660.  
  12661.        cgetrec 5
  12662.        if $CFLAG_FLD = "A" return  ;skip something if flag is set
  12663.  
  12664.        And when your script ends:
  12665.  
  12666.        cgetrec 5
  12667.        assign $CFLAG_FLD " "  ;clear the flag
  12668.        cputrec
  12669.  
  12670.      $CLOC_FLD________________________________________________________________
  12671.  
  12672.       The BIF/Location of the currently loaded Tagger catalog record
  12673.       (CGETREC).  Compare $CLOC_FLD to $BIF_NAME to see if the file is
  12674.       available for download on the current BBS (IF $CLOC_FLD = $BIF_NAME).
  12675.  
  12676.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12677.       on using the $Cxxxx_FLD variables.
  12678.  
  12679.      $CNAME_FLD_______________________________________________________________
  12680.  
  12681.       The Filename of the currently loaded Tagger catalog record (CGETREC).
  12682.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12683.       on using the $Cxxxx_FLD variables.
  12684.  
  12685.  
  12686.      $COM_PORT________________________________________________________________
  12687.  
  12688.       The current COM port (1 - 8).
  12689.  
  12690.      $CPRIORITY_FLD___________________________________________________________
  12691.  
  12692.       The 'Transfer Priority' of the currently loaded catalog record
  12693.       (CGETREC).  $CPRIORITY_FLD allows you to check or set the transfer
  12694.       priority of the current file.  Example:
  12695.        
  12696.        cgetrec
  12697.        assign $CPRIORITY_FLD 10   ;set to priority 10 (100 is the default)
  12698.        cputrec                    
  12699.  
  12700.       This will only work on either Tagged or Noted files.  Check $CTAG_FLD to
  12701.       see whether a file is 'T'agged or 'N'oted.  When using the Tag
  12702.  
  12703.  
  12704.  
  12705.  
  12706.      Intellicomm v2.01               SCRIPT.DOC                            201
  12707.      
  12708.      
  12709.  
  12710.       Status/Location sort order (see CSETSORT in SCRTUTOR.DOC), files are
  12711.       sorted by Tag Status, Location, Download Priority (a number from 1-200,
  12712.       1 being top priority), file Conference, Filename.  I.e. all Tagged files
  12713.       for a given BBS are grouped together, with the highest priority file
  12714.       first, the next-highest second, etc.  By simply using the Tag
  12715.       Status/Location index and using CGETREC, you'll get all the Tagged files
  12716.       in the proper order, according to the priorities the user has set.
  12717.  
  12718.      $COM_SPEED_______________________________________________________________
  12719.  
  12720.       The current COM port speed (300-115200).
  12721.  
  12722.      $CREC_STAT_______________________________________________________________
  12723.  
  12724.       The status of the currently loaded Tagger catalog record (CGETREC).
  12725.       "D" = Deleted, "A" = Active.
  12726.  
  12727.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12728.       on using the $Cxxxx_FLD variables.
  12729.  
  12730.      $CSIZE_FLD_______________________________________________________________
  12731.  
  12732.       The File Size of the currently loaded Tagger catalog record (CGETREC).
  12733.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12734.       on using the $Cxxxx_FLD variables.
  12735.  
  12736.      $CSORT_DIR_______________________________________________________________
  12737.  
  12738.       Read only.  The sorting direction of the currently open catalog.  0 =
  12739.       Forward, 1 = Reversed.  Use CSETSORT to change the sort direction.
  12740.  
  12741.      $CSORT_ORDER_____________________________________________________________
  12742.  
  12743.       Read only.  The sorting direction of the currently open catalog.  0 =
  12744.       Forward, 1 = Reversed.  Use CSETSORT to change the sort direction.
  12745.  
  12746.      $CTAG_FLD________________________________________________________________
  12747.  
  12748.       The Tag Status of the currently loaded Tagger catalog record (CGETREC). 
  12749.       N = Noted, T = Tagged, U = Untagged.
  12750.  
  12751.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12752.       on using the $Cxxxx_FLD variables.
  12753.  
  12754.      $CTOTAL__________________________________________________________________
  12755.  
  12756.       Read only.  The total number of records in the currently open Tagger
  12757.       catalog.
  12758.  
  12759.      $CVTOTAL_________________________________________________________________
  12760.  
  12761.       Read only.  The total number of records that are 'viewable' in the
  12762.       currently open Tagger catalog.  $VIEW_DATE filters out catalog records
  12763.       that are older than a given date, so $CTOTAL and $CVTOTAL will often
  12764.  
  12765.  
  12766.  
  12767.  
  12768.      Intellicomm v2.01               SCRIPT.DOC                            202
  12769.      
  12770.      
  12771.  
  12772.       differ.  ASSIGN $VIEW_DATE "19800101" to make all records 'viewable'.
  12773.  
  12774.      $CURDIR__________________________________________________________________
  12775.  
  12776.       The current DOS drive and directory in the format D:\ or D:\PATH\ (a
  12777.       trailing slash always exists).
  12778.  
  12779.      $CURDRIVE________________________________________________________________
  12780.  
  12781.       The current DOS disk drive, without the colon (A, B, C, etc).
  12782.  
  12783.      $DATE____________________________________________________________________
  12784.  
  12785.       Read only.  The current system date.  $DATE is formatted according to
  12786.       the main setup options "Date Format" [*date] and "Date Separator"
  12787.       [*datesep or $DSEP] on the General Settings screen.
  12788.  
  12789.      $DAY_____________________________________________________________________
  12790.  
  12791.       Read only.  The current system day of month (1-31).
  12792.  
  12793.      $DL_DIR__________________________________________________________________
  12794.  
  12795.       The current Download Directory.  If the currently loaded BIF has a
  12796.       Download Dir defined (BIF File screen), $DL_DIR will be set to the BIF
  12797.       Directory.  If no Download Dir is defined in the BIF, the main setup
  12798.       Download Directory is assumed (main setup, Filenames and Paths screen).
  12799.  
  12800.      $DL_PROTOCOL_____________________________________________________________
  12801.  
  12802.       The 'Receive Files' protocol defined in the currently loaded BIF. 
  12803.       $DL_PROTOCOL uses the same format for protocols (a single letter) that
  12804.       the DOWNLOAD command expects.  Thus you can use DOWNLOAD $DL_PROTOCOL to
  12805.       download files using the protocol defined in the BIF.
  12806.  
  12807.      $DOORWAY_________________________________________________________________
  12808.  
  12809.       The current status of Doorway Mode; 0 = Off, 1 = On.
  12810.  
  12811.      $DOW_____________________________________________________________________
  12812.  
  12813.       The current day-of-week.  1 = Sunday, 2 = Monday, 3 = Tuesday, 4 =
  12814.       Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.
  12815.  
  12816.      $DSEP____________________________________________________________________
  12817.  
  12818.       The Date Separator character defined on the main setup General Settings
  12819.       screen.
  12820.  
  12821.      $ECHO____________________________________________________________________
  12822.  
  12823.       Terminal 'echo' status; 0 = Off, 1 = On.  When echo is on, characters
  12824.       typed on the keyboard are also printed to the screen.
  12825.  
  12826.  
  12827.  
  12828.  
  12829.      Intellicomm v2.01               SCRIPT.DOC                            203
  12830.      
  12831.      
  12832.  
  12833.      $ERRORLEVEL______________________________________________________________
  12834.  
  12835.       Used to check the results of many script commands.  See the ERRORLEVEL
  12836.       sections in the Detailed Command Summary section above.
  12837.  
  12838.      $FARCH___________________________________________________________________
  12839.  
  12840.       Read only.  The state of the file Archive attribute; + = On, - = Off. 
  12841.       EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12842.       is found.
  12843.  
  12844.      $FDATE___________________________________________________________________
  12845.  
  12846.       Read only.  The file modification date in the format defined on the main
  12847.       setup General Settings screen (Date Format, Date Separator).  EXIST,
  12848.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12849.       found.
  12850.  
  12851.      $FDAY____________________________________________________________________
  12852.  
  12853.       Read only.  The file modification date, day of month only (1-31). 
  12854.       EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12855.       is found.
  12856.  
  12857.      $FHIDDEN_________________________________________________________________
  12858.  
  12859.       Read only.  The state of the file Hidden attribute; + = On, - = Off. 
  12860.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12861.       NOTEXIT cannot find hidden files).
  12862.  
  12863.      $FHOUR___________________________________________________________________
  12864.  
  12865.       Read only.  The file modification time, hour only (0-23).  EXIST,
  12866.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12867.       found.
  12868.  
  12869.      $FMIN____________________________________________________________________
  12870.  
  12871.       Read only.  The file modification time, minute only (0-59).  EXIST,
  12872.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12873.       found.
  12874.  
  12875.      $FMONTH__________________________________________________________________
  12876.  
  12877.       Read only.  The file modification date, month only (1-12).  EXIST,
  12878.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12879.       found.
  12880.  
  12881.      $FRDONLY_________________________________________________________________
  12882.  
  12883.       Read only.  The state of the file Read Only attribute; + = On, - = Off.  
  12884.        EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12885.       is found. 
  12886.  
  12887.  
  12888.  
  12889.  
  12890.      Intellicomm v2.01               SCRIPT.DOC                            204
  12891.      
  12892.      
  12893.  
  12894.       Files with the Read Only attribute set cannot be deleted or overwritten.
  12895.  
  12896.      $FSEC____________________________________________________________________
  12897.  
  12898.       Read only.  The file modification time, second only (0-59).  EXIST,
  12899.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12900.       found.
  12901.  
  12902.      $FSIZE___________________________________________________________________
  12903.  
  12904.       Read only.  The file size.  EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set
  12905.       this variable if the file is found.
  12906.  
  12907.      $FSUBDIR_________________________________________________________________
  12908.  
  12909.       Read only.  The state of the Subdirectory attribute; + = On, - = Off. 
  12910.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12911.       NOTEXIT cannot find subdirectories).
  12912.  
  12913.       If the Subdirectory attribute is set, the file is a subdirectory (these
  12914.       directory entries are marked with <DIR> in Icom's File Manager).
  12915.  
  12916.  
  12917.      $FSYSTEM_________________________________________________________________
  12918.  
  12919.       Read only.  The state of the System File attribute; + = On, - = Off. 
  12920.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12921.       NOTEXIT cannot find System files).
  12922.  
  12923.      $FTIME___________________________________________________________________
  12924.  
  12925.       Read only.  The file modification time in the format defined on the main
  12926.       setup General Settings screen (Time Format, Time Separator).  EXIST,
  12927.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12928.       found.
  12929.  
  12930.      $FVOLID__________________________________________________________________
  12931.  
  12932.       Read only.  The state of the Volume ID attribute; + = On, - = Off. 
  12933.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12934.       NOTEXIT cannot find Volume ID's).
  12935.  
  12936.       Only one file per disk (in the root directory) has the Volume ID
  12937.       attribute set.
  12938.  
  12939.      $FULL_SCRIPT_NAME________________________________________________________
  12940.  
  12941.       The full D:\PATH\FILENAME.EXT of the currently executing script.
  12942.  
  12943.      $FYEAR___________________________________________________________________
  12944.  
  12945.       Read only.  The file modification date, year only (1990, 1995, 2000,
  12946.       etc).  EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the
  12947.       file is found.
  12948.  
  12949.  
  12950.  
  12951.  
  12952.      Intellicomm v2.01               SCRIPT.DOC                            205
  12953.      
  12954.      
  12955.  
  12956.      $HOME_DIR________________________________________________________________
  12957.  
  12958.       The D:\PATH\ where ICOM.EXE and many of Intellicomm's data files reside. 
  12959.       $HOME_DIR can be overridden with a SET ICOM=D:\PATH\ command (sets an
  12960.       environment variable) from the DOS prompt or AUTOEXEC.BAT file.
  12961.  
  12962.      $HOTKEY_1________________________________________________________________
  12963.      $HOTKEY_2________________________________________________________________
  12964.      $HOTKEY_3________________________________________________________________
  12965.      $HOTKEY_4________________________________________________________________
  12966.      $HOTKEY_5________________________________________________________________
  12967.  
  12968.       Allows you to define up to 5 'hotkeys' for use with the GETS and BOXGETS
  12969.       commands.  The hotkeys you define must be extended keycodes such as an
  12970.       [Alt] key combination ([Alt-A], [Alt-B], etc).  See the KEYBOARD CODES
  12971.       appendix for appropriate key codes.
  12972.  
  12973.       Please see the BOXGETS command for an example of usage.
  12974.  
  12975.      $HOUR____________________________________________________________________
  12976.  
  12977.       Read only.  The current system time of day, hour only (0-23; 0 =
  12978.       Midnight).
  12979.  
  12980.  
  12981.      $HSEC____________________________________________________________________
  12982.  
  12983.       Read only.  The current system time of day, hundredth of a second only
  12984.       (0-99).
  12985.  
  12986.      $INI_NAME________________________________________________________________
  12987.  
  12988.       The currently loaded .INI (main setup) file.
  12989.  
  12990.      $KEY_ALTQ________________________________________________________________
  12991.  
  12992.       If set to 0 (zero), the script processor ignores [Alt-Q] keypresses
  12993.       which prevents the user from aborting the script.  This can be useful
  12994.       when you have some important cleanup work to do before your script ends. 
  12995.       If set to any number other than zero, [Alt-Q] pops up the Job/Script
  12996.       Control Menu.
  12997.  
  12998.      $KEY_CHECK_______________________________________________________________
  12999.  
  13000.       If set to 0 (zero), the script processor doesn't check for any keys at
  13001.       all, effectively disabling all Intellicomm functions.  You can then
  13002.       handle every keystroke as you see fit.
  13003.  
  13004.       For advanced script writers only.
  13005.  
  13006.      $KEY_FILTER______________________________________________________________
  13007.  
  13008.       Allows you to define up to ten normal ASCII characters that BOXGETS,
  13009.       GETS, and GETSXY will not accept.  For example, if you're prompting the
  13010.  
  13011.  
  13012.  
  13013.  
  13014.      Intellicomm v2.01               SCRIPT.DOC                            206
  13015.      
  13016.      
  13017.  
  13018.       user for a filename, and you don't want to accept wildcards (* and ?):
  13019.        
  13020.        assign $KEY_FILTER "*?"
  13021.        gets somevariable 8      ;GETS will not allow * or ? to be entered
  13022.        assign $KEY_FILTER ""    ;restore to normal
  13023.  
  13024.      $LINEFEED________________________________________________________________
  13025.  
  13026.       If set to 0 (zero), the Terminal does not add line feed characters when
  13027.       carriage returns are received from the COM port.  If set to any number
  13028.       other than zero, line feeds are automatically added by the Terminal
  13029.       display routines whenever a carriage return is received.
  13030.  
  13031.       If lines from the BBS/modem overwrite one another, ASSIGN $LINEFEED 1. 
  13032.       If lines from the BBS/modem are double-spaced, ASSIGN $LINEFEED 0.
  13033.  
  13034.      $LST_DIR_________________________________________________________________
  13035.  
  13036.       The D:\PATH\ that BBS new files lists are captured to (automated jobs,
  13037.       "Get new files list" task).
  13038.  
  13039.      $MAJOR_VERSION___________________________________________________________
  13040.  
  13041.       Read only.  The major Intellicomm version number (2) to the left of the
  13042.       decimal point.
  13043.      $MENUSELECTION___________________________________________________________
  13044.  
  13045.       Set to the menu item selected by MENUBAR, MENUBOXH and MENUBOXV.
  13046.  
  13047.      $MIN_____________________________________________________________________
  13048.  
  13049.       Read only.  The current system time of day, minute only (0-59).
  13050.  
  13051.      $MINOR_VERSION___________________________________________________________
  13052.  
  13053.       Read only.  The minor Intellicomm version number to the left of the
  13054.       decimal point.  Intellicomm v2.01 has a $MINOR_VERSION of 1, v2.10 would
  13055.       have a minor version of 10 (ten), etc.
  13056.  
  13057.      $MONTH___________________________________________________________________
  13058.  
  13059.       Read only.  The current system date, month only (1-12; 1 = January).
  13060.  
  13061.      $MSG_DIR_________________________________________________________________
  13062.  
  13063.       The current Message Directory (where message packets should be
  13064.       downloaded to).  If the currently loaded BIF has a Message Dir defined
  13065.       (BIF Message screen), $MSG_DIR will be set to the BIF Directory.  If no
  13066.       Message Dir is defined in the BIF, the main setup Message Directory is
  13067.       assumed (main setup, Filenames and Paths screen).
  13068.  
  13069.       NOTE: If your script downloads mail packets, it's up to you to do the
  13070.       following in order to get the packet into the proper directory:
  13071.  
  13072.  
  13073.  
  13074.  
  13075.      Intellicomm v2.01               SCRIPT.DOC                            207
  13076.      
  13077.      
  13078.  
  13079.       assign OldDLDir $DL_DIR    ;save existing D/L Directory
  13080.       assign $DL_DIR $MSG_DIR    ;now assign the message dir to the D/L dir
  13081.  
  13082.       download $MSG_PROTOCOL ""  ;now downloads into the Message Directory
  13083.       
  13084.       assign $DL_DIR OldDLDir    ;put it back the way it was
  13085.  
  13086.      $MSG_PROTOCOL____________________________________________________________
  13087.  
  13088.       The 'Receive Mail' protocol defined in the currently loaded BIF. 
  13089.       $MSG_PROTOCOL uses the same format for protocols (a single letter) that
  13090.       the DOWNLOAD command expects.  Thus you can use DOWNLOAD $MSG_PROTOCOL
  13091.       to download mail packets using the protocol defined in the BIF.
  13092.  
  13093.      $NORM_COLOR______________________________________________________________
  13094.  
  13095.       The color of normal text on all Intellicomm displays.
  13096.  
  13097.      $PASSWORD________________________________________________________________
  13098.  
  13099.       The Logon Password defined in the currently loaded BIF.
  13100.  
  13101.      $OPSYSTYPE_______________________________________________________________
  13102.  
  13103.       Allows you to determine which Operating System your script is running
  13104.       under:  0 = DOS, 1 = Windows, 2 = OS/2, 3 = DESQview.  Example:
  13105.  
  13106.        switch $OPSYSTYPE
  13107.         case 0
  13108.          print "DOS detected."
  13109.         endcase
  13110.         case 1
  13111.          print "Windows v3.x detected."
  13112.         endcase
  13113.         case 2
  13114.          print "OS/2 v2.x detected."
  13115.         endcase
  13116.         case 3
  13117.          print "DESQview detected."
  13118.         endcase
  13119.        endswitch
  13120.  
  13121.       Windows versions lower than v3.00 and OS/2 versions lower than v2.0 are
  13122.       ignored and will be reported as DOS (0).
  13123.  
  13124.      $PRN_____________________________________________________________________
  13125.  
  13126.       The printer device as defined on the main setup / Filenames and Paths
  13127.       screen (defaults to PRN).
  13128.  
  13129.      $REP_DIR_________________________________________________________________
  13130.  
  13131.       The current Reply Directory (where message packets should be downloaded
  13132.       to).  If the currently loaded BIF has a Reply Dir defined (BIF Message
  13133.  
  13134.  
  13135.  
  13136.  
  13137.      Intellicomm v2.01               SCRIPT.DOC                            208
  13138.      
  13139.      
  13140.  
  13141.       screen), $REP_DIR will be set to the BIF Directory.  If no Reply Dir is
  13142.       defined in the BIF, the main setup Reply Directory is assumed (main
  13143.       setup, Filenames and Paths screen).
  13144.  
  13145.       NOTE: If your script uploads reply packets, it's up to you to specify
  13146.       the proper directory when you upload:
  13147.  
  13148.       upload $REP_PROTOCOL $REP_DIR "PACKET.REP"
  13149.  
  13150.      $REP_PROTOCOL____________________________________________________________
  13151.  
  13152.       The 'Send Mail' protocol defined in the currently loaded BIF. 
  13153.       $REP_PROTOCOL uses the same format for protocols (a single letter) that
  13154.       the UPLOAD command expects.  Thus you can use UPLOAD $REP_PROTOCOL to
  13155.       upload mail packets using the protocol defined in the BIF.
  13156.  
  13157.      $RXCNT___________________________________________________________________
  13158.  
  13159.       Reports the number of characters currently waiting in the communications
  13160.       Receive Buffer.
  13161.  
  13162.      $SCRIPT_DIR______________________________________________________________
  13163.  
  13164.       The Script Directory (D:\PATH\ where Icom scripts are located).
  13165.  
  13166.      $SCRIPT_NAME_____________________________________________________________
  13167.  
  13168.       The FILENAME.EXT (no D:\PATH\) of the currently executing script.  Use
  13169.       $FULL_SCRIPT_NAME if you require the full D:\PATH\FILENAME.EXT.
  13170.  
  13171.      $SCRN_COLOR______________________________________________________________
  13172.  
  13173.       The current screen color.  Changing $SCRN_COLOR affects only NEW
  13174.       information printed on the screen.  It does not change the color of
  13175.       EXISTING information on the screen.  To display the entire screen in a
  13176.       new color, you must use CLS (clear screen) after changing $SCRN_COLOR.
  13177.  
  13178.      $SCRN_HEIGHT_____________________________________________________________
  13179.  
  13180.       Read only.  The total number of rows (lines top to bottom) available on
  13181.       the video display.  25 rows is the usual but EGA displays can also use
  13182.       43 lines, and VGA displays can use 50 lines.
  13183.  
  13184.      $SCRN_WIDTH______________________________________________________________
  13185.  
  13186.       Read only.  The total number of columns (characters left to right)
  13187.       available on the video display.  80 columns is the usual.
  13188.  
  13189.      $SCRN_WRAP_______________________________________________________________
  13190.  
  13191.       Determines whether the Terminal (and PRINT, PRINTNC, PAUSE commands)
  13192.       truncates or wraps lines that are longer than can fit in the current
  13193.       video display WINDOW.  If $SCRN_WRAP is zero, lines are truncated at
  13194.       $WND_RIGHT (the right-most column of the current WINDOW).  If $SCRN_WRAP
  13195.  
  13196.  
  13197.  
  13198.  
  13199.      Intellicomm v2.01               SCRIPT.DOC                            209
  13200.      
  13201.      
  13202.  
  13203.       is any number other than zero, lines wrapped to the next display line. 
  13204.       Setting $SCRN_WRAP to 1 does not give you word processor type 'word
  13205.       wrapping'.  Words will be split/wrapped to the next line right in the
  13206.       middle of a word if necessary.
  13207.  
  13208.      $SCRN_X__________________________________________________________________
  13209.  
  13210.       Read only.  The current X position (screen column, left to right) of the
  13211.       cursor.  Use GOTOXY to change the cursor position.
  13212.  
  13213.      $SCRN_Y__________________________________________________________________
  13214.  
  13215.       Read only.  The current Y position (screen row, top to bottom) of the
  13216.       cursor.  Use GOTOXY to change the cursor position.
  13217.  
  13218.      $SEC_____________________________________________________________________
  13219.  
  13220.       Read only.  The current system time of day, second only (0-59).
  13221.  
  13222.      $SEND_CR_________________________________________________________________
  13223.  
  13224.       Determines whether the SEND, SENDNP, and SENDNPC commands add a carriage
  13225.       return to the text they send.  If $SEND_CR is zero, no CR is added. 
  13226.       Otherwise a CR is added.
  13227.  
  13228.      $SOUND___________________________________________________________________
  13229.  
  13230.       Determines whether Intellicomm makes any sounds at all on the PC
  13231.       speaker.  If $SOUND is zero, ^G (BELL) characters from the BBS are not
  13232.       heard, nor are alarms, nor do the script ALARM or BEEP commands make any
  13233.       sound.
  13234.  
  13235.      $STAT_COLOR______________________________________________________________
  13236.  
  13237.       The color of the Terminal status line.
  13238.  
  13239.      $STAT_ON_________________________________________________________________
  13240.  
  13241.       Holds the current display status of the Terminal Mode status line (all
  13242.       scripts execute from Terminal Mode).  0 = Off, 1 = On.  You can also
  13243.       hide or unhide the status line by ASSIGNing 0 or 1 to this variable.
  13244.  
  13245.       Changing the state of this variable (ASSIGN $STAT_ON x) automatically
  13246.       resets $WND_BTM (the current WINDOW bottom screen line).  Further if you
  13247.       previously used a WNDOPEN command $WND_BTM will *not* be set properly to
  13248.       reflect the new screen size when you call WNDCLOSE (WNDOPEN saves all
  13249.       $WND_* coordinates when you call it, and restores those same values when
  13250.       you call WNDCLOSE).  Thus if you plan on using either the WINDOW or
  13251.       WNDOPEN commands in your script you should change $STAT_ON *first* or
  13252.       you will lose your current bottom window limit, and will not get the
  13253.       proper $WND_BTM when you call WNDCLOSE.  Example:
  13254.  
  13255.       WNDOPEN "Box Title" 5 5 75 20   ;20 is the bottom screen row of the box
  13256.       PRINT $WND_BTM                  ;$WND_BTM is now 19 (20=box border)
  13257.  
  13258.  
  13259.  
  13260.  
  13261.      Intellicomm v2.01               SCRIPT.DOC                            210
  13262.      
  13263.      
  13264.  
  13265.       ASSIGN $STAT_ON 0               ;turn off the status line
  13266.       PRINT $WND_BTM                  ;$WND_BTM is now $SCRN_HEIGHT (the full
  13267.                                       ; height of the screen), not 19.  PRINT
  13268.                                       ; would write over the bottom box border
  13269.                                       ; right to the end of the screen
  13270.       WNDCLOSE                        ;resets $WND_BTM to whatever value it
  13271.                                       ; was when WNDOPEN was called.  I.e.
  13272.                                       ; the change in $STAT_ON is lost and
  13273.                                       ; though the status line will not be
  13274.                                       ; VISIBLE, the bottom screen line will
  13275.                                       ; not be used.
  13276.        
  13277.        ;this is the correct way to do it:
  13278.  
  13279.       ASSIGN $STAT_ON 0               ;turn off FIRST (resets $WND_BTM)
  13280.       WNDOPEN "Box Title" 5 5 75 20   ;$WND_BTM is now set to row 19
  13281.                                       ; (20=window border), and WNDOPEN 
  13282.                                       ; saved the proper $WND_BTM value.
  13283.       WNDCLOSE                        ;$WND_BTM is now reset to the proper
  13284.                                       ; value, since it was reset
  13285.                                       ; BEFORE the call to WNDOPEN
  13286.  
  13287.       $WND_BTM is also lost when you ASSIGN $STAT_ON 1 to turn the status line
  13288.       back on.  Motto: if changing $STAT_ON, it is best done at the beginning
  13289.       and end of your scripts (unless you don't use any WNDOPEN or WINDOW
  13290.       commands... if that's the case it really doesn't matter).  You should
  13291.       also save the old display status before changing $STAT_ON since as with
  13292.       most System Variables the value is NOT automatically restored when your
  13293.       script ends (you may want to leave it that way... Icom has no way of
  13294.       knowing):
  13295.       
  13296.       VARIABLE old_stat_on $STAT_ON   ;define 'old_stat_on', store the value
  13297.      of
  13298.                                       ; $STAT_ON (0 or 1) in it.
  13299.       ASSIGN $STAT_ON 0               ;turn it off
  13300.        ...                            ;body of script here
  13301.       ASSIGN $STAT_ON old_stat_on     ;restore original value
  13302.       
  13303.  
  13304.      $TERM_COLOR______________________________________________________________
  13305.  
  13306.       The DEFAULT color of the terminal display (not the current color;
  13307.       $SCRN_COLOR holds the current color).
  13308.  
  13309.      $TIME____________________________________________________________________
  13310.  
  13311.       Read only.  The current system time.  $TIME is formatted according to
  13312.       the main setup options "Time Format" [*time] and "Time Separator"
  13313.       [*timesep or $TSEP] on the General Settings screen.
  13314.  
  13315.      $TSEP____________________________________________________________________
  13316.  
  13317.       The Time Separator character defined on the main setup General Settings
  13318.       screen.
  13319.  
  13320.  
  13321.  
  13322.  
  13323.      Intellicomm v2.01               SCRIPT.DOC                            211
  13324.      
  13325.      
  13326.  
  13327.      $TXCNT___________________________________________________________________
  13328.  
  13329.       Reports the number of characters currently waiting in the communications
  13330.       Transmit Buffer.
  13331.  
  13332.      $UL_PATH_________________________________________________________________
  13333.  
  13334.       The current Upload PATH.  If the currently loaded BIF has an Upload PATH
  13335.       defined (BIF File screen), $UL_PATH will be set to the BIF path.  If no
  13336.       Upload PATH is defined in the BIF, the main setup Upload PATH is assumed
  13337.       (main setup, Filenames and Paths screen).
  13338.  
  13339.       Directories on the Upload PATH are defined in the same manner as the
  13340.       regular DOS PATH:
  13341.  
  13342.       "C:\DIR1;C:\DIR2;C:\DIR3 ...etc"
  13343.  
  13344.       When UPLOAD is used, all directories in the Upload PATH are searched to
  13345.       locate the file(s) to upload.
  13346.  
  13347.      $UL_PROTOCOL_____________________________________________________________
  13348.  
  13349.       The 'Send Files' protocol defined in the currently loaded BIF. 
  13350.       $UL_PROTOCOL uses the same format for protocols (a single letter) that
  13351.       the UPLOAD command expects.  Thus you can use UPLOAD $UL_PROTOCOL to
  13352.       upload files using the protocol defined in the BIF.
  13353.  
  13354.      $VIEW_DATE_______________________________________________________________
  13355.  
  13356.       The View Date of the currently open catalog.  Any catalog records with a
  13357.       Catalog Date ($CCDATE_FLD) older than $VIEW_DATE are ignored, and will
  13358.       not be returned by CGETREC.  ASSIGN $VIEW_DATE "19800101" (January 1st,
  13359.       1980) to disable the $VIEW_DATE feature.
  13360.  
  13361.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  13362.       on using the $VIEW_DATE variable.
  13363.  
  13364.      $WND_BTM_________________________________________________________________
  13365.  
  13366.       The bottom video row of the current WINDOW.
  13367.  
  13368.      $WND_HEIGHT______________________________________________________________
  13369.  
  13370.       The total number of screen rows (top to bottom) in the current WINDOW.
  13371.  
  13372.      $WND_LEFT________________________________________________________________
  13373.  
  13374.       The left-most video column of the current WINDOW.
  13375.  
  13376.      $WND_RIGHT_______________________________________________________________
  13377.  
  13378.       The right-most video column of the current WINDOW.
  13379.  
  13380.      $WND_TOP_________________________________________________________________
  13381.  
  13382.  
  13383.  
  13384.  
  13385.      Intellicomm v2.01               SCRIPT.DOC                            212
  13386.      
  13387.      
  13388.  
  13389.       The top video row of the current WINDOW.
  13390.  
  13391.      $WND_WIDTH_______________________________________________________________
  13392.  
  13393.       The total number of screen columns (left to right) in the current
  13394.      WINDOW.
  13395.  
  13396.      $YEAR____________________________________________________________________
  13397.  
  13398.       Read only.  The current system date, year only.
  13399.  
  13400.  
  13401.  
  13402.  
  13403.      Intellicomm v2.01               SCRIPT.DOC                            213
  13404.      
  13405.      
  13406.  
  13407.  
  13408.                       B.  BIF VARIABLES (Advanced Users Only)
  13409.  
  13410.      BIF Variables allow you to access every configurable item in any BIF
  13411.      (other than the BIF Notes).  They can be used in any script command that
  13412.      takes a parameter, instead of specifying constant (hardcoded) data.
  13413.  
  13414.      BIF Variables start with an asterisk (*) and are then immediately
  13415.      followed by the BIF 'section' and 'tag' of the item.
  13416.  
  13417.             PRINT *[G]desc
  13418.                   | |  |
  13419.       Asterisk----  |  |
  13420.                     |  |
  13421.       BIF Section---   |
  13422.                        |
  13423.       BIF Tag----------
  13424.  
  13425.      The command above tells Intellicomm to access the [G]eneral BIF section
  13426.      (General screen as in the BIF Editor) for the tag "desc" (short for
  13427.      description; the BBS/Host name), and print the value to the screen.
  13428.  
  13429.      You may also wish to use BIF Variables in WHEN commands:
  13430.  
  13431.       WHEN *[L]namp SEND *[L]namc
  13432.  
  13433.      This sends the BIF namc 'name command' (response) WHEN the BIF namp 'name
  13434.      prompt' is found.  Both items are in the BIF [L]ogon section.
  13435.  
  13436.      You can do the same with ANY script command that takes a parameter,
  13437.      instead of specifying constant text.  All the BIF sections and tags are
  13438.      listed in this appendix, along with any special conditions or
  13439.      considerations.
  13440.  
  13441.      NOTE: BIF Variables cannot change the BIF on-disk.  BIFs are loaded from
  13442.      disk into MEMORY automatically by Intellicomm when you dial a BBS (via
  13443.      manual or automated means) or when you use the LOADBIF command in your
  13444.      script.  If you change BIF Variables via ASSIGN or another script
  13445.      assignment command and wish to save the changes to disk you must use
  13446.      SAVEBIF to write the changes to disk.  The $BIF_NAME System Variable
  13447.      holds the filename of the currently loaded BIF (without the .BIF
  13448.      extension).
  13449.  
  13450.      As with the System Variables, if you CHANGE any of the BIF items using
  13451.      ASSIGN or any other script assignment command, you change the data that
  13452.      Icom is working with as well, for the duration of the session or until
  13453.      another BIF is loaded.  To avoid potential problems when running scripts
  13454.      from automated jobs, you can either save/restore original BIF data as we
  13455.      did above with the System Variables, or can simply use LOADBIF $BIF_NAME
  13456.      when your script ends, to reset all the BIF variables to their original
  13457.      values.
  13458.  
  13459.      Below, are all six BIF screens with the appropriate BIF Variable to use
  13460.      in a script displayed where the BIF data would normally be displayed:
  13461.  
  13462.  
  13463.  
  13464.  
  13465.      Intellicomm v2.01               SCRIPT.DOC                            214
  13466.      
  13467.      
  13468.  
  13469.      ╔═╡ BIF Editor Θ Editing VARIABLE.BIF ╞ General BBS Information ╞═══════╗
  13470.      ║ BBS/Host Name  > *[G]desc           Message Type   > *[G]mtyp         ║
  13471.      ║ Phone Number   > *[G]phn1           Bank Type      > *[G]btyp         ║
  13472.      ║ Phone Number   > *[G]phn2           LD Service . . . *[G]ldsv         ║
  13473.      ║ Phone Number   > *[G]phn3           City/Address . . *[G]city         ║
  13474.      ║ Phone Number   > *[G]phn4           CR w/Commands? . *[G]adcr         ║
  13475.      ║ Phone Number   > *[G]phn5           Add Line Feeds?  *[G]adlf         ║
  13476.      ║ Port Settings  > *[G]port           Case-sensitive?  *[G]case         ║
  13477.      ║ Dial Prefix  . . *[G]dpre           Connect Command  *[G]conc         ║
  13478.      ║ Max. Redials . . *[G]datt           Gen. Menu Exit . *[G]mcan         ║
  13479.      ╟─┤ Protocols ├───────────────────────┤ Miscellaneous/Timeouts ├────────╢
  13480.      ║ Send Mail  . . . *[G]mspr           Last Connected . *[G]date         ║
  13481.      ║  BBS Letter  . . *[G]msbl           Total Connects . *[G]nses         ║
  13482.      ║ Receive Mail . . *[G]mrpr           Response Delay . *[G]rdel         ║
  13483.      ║  BBS Letter  . . *[G]mrbl           BS Protection  . *[G]bspt         ║
  13484.      ║ Send Files . . . *[G]fspr           Logon Timeout  . *[G]lout         ║
  13485.      ║  BBS Letter  . . *[G]fsbl           General Timeout  *[G]gout         ║
  13486.      ║ Receive Files  . *[G]frpr           Max. Timeouts  . *[G]tmax         ║
  13487.      ║  BBS Letter  . . *[G]frbl           Max. Online Time *[G]monl         ║
  13488.      ╚═══════════════════════════════════════════════════════════════════════╝
  13489.  
  13490.      ╔═╡ Logon/Global Commands ╞═══════════╡ Logon/Global Prompts ╞══════════╗
  13491.      ║ [Escape] Answer  *[L]escc           [Escape] Prompt  *[L]escp         ║
  13492.      ║ Your Logon Name> *[L]namc           Name . . . . . . *[L]namp         ║
  13493.      ║ Password Answer> $PASSWORD          Password . . . . *[L]pasp         ║
  13494.      ║ Mode/Language  > *[L]lanc           Mode/Language  . *[L]lanp         ║
  13495.      ║ Confirm Answer . *[L]ecnc           Confirm  . . . . *[L]ecnp         ║
  13496.      ║ Graphics Answer  *[L]grac           Graphics . . . . *[L]grap         ║
  13497.      ║ Scan Answer  . . *[L]scac           Scan Messages  . *[L]scap         ║
  13498.      ║ Pause Answer . . *[L]pauc           Pause  . . . . . *[L]paup         ║
  13499.      ║ No More  . . . . *[L]nomc           More . . . . . . *[L]morp         ║
  13500.      ║ Birth Date . . . *[L]bdtc           Enter Birth Date *[L]bdps         ║
  13501.      ║ Home Phone . . . *[L]phnc           Enter Home Phone *[L]phnp         ║
  13502.      ║ Startup Command  *[L]icom           Main Menu A  . . *[L]mnap         ║
  13503.      ║ Logoff . . . . . *[L]lofc           Main Menu B  . . *[L]mnbp         ║
  13504.      ║ Exit Command . . *[L]xitc           Logged Off . . . *[L]lofp         ║
  13505.      ╚═══════════════════════════════════════════════════════════════════════╝
  13506.  
  13507.      ╔═╡ Message Commands ╞════════════════╡ Message Prompts ╞═══════════════╗
  13508.      ║ Access Msg Menu> *[M]ames           Message Menu . . *[M]mmnp         ║
  13509.      ║ Send Replies . . *[M]senc           Send Replies Now *[M]rulp         ║
  13510.      ║ Reply Filename > *[M]rnam           Replies Accepted *[M]rokp         ║
  13511.      ║ Confirm Answer . *[M]crec           Confirm Receive  *[M]crep         ║
  13512.      ║ General Read . . *[M]grdc           Receive Messages *[M]mdlp         ║
  13513.      ║ Personal Read  . *[M]prdc           Receive Success  *[M]mokp         ║
  13514.      ║ Msg Filename   > *[M]mnam           More Mail Found  *[M]mmfp         ║
  13515.      ║ Extract Newfiles *[M]mnew           No Mail Found  . *[M]mnop         ║
  13516.      ║                                     No Time Left . . *[M]mntp         ║
  13517.      ║ More Answer  . . *[M]mmoc           Message More . . *[M]mmop         ║
  13518.      ║ Leave Msg Menu . *[M]lmmc           Message Pause  . *[M]mpap         ║
  13519.      ║ Logoff Msg Menu  *[M]gmmc           Enter Protocol . *[M]mprp         ║
  13520.      ║ Reply Dir  . . . *[M]repd                                             ║
  13521.      ║ Message Dir  . . *[M]msgd                                             ║
  13522.      ╚═══════════════════════════════════════════════════════════════════════╝
  13523.  
  13524.  
  13525.  
  13526.  
  13527.      Intellicomm v2.01               SCRIPT.DOC                            215
  13528.      
  13529.      
  13530.  
  13531.      ╔═╡ Bank Commands ╞═══════════════════╡ Bank Prompts ╞══════════════════╗
  13532.      ║ Access Bnk Menu> *[B]abnk           Bank Menu  . . . *[B]bmnp         ║
  13533.      ║ Deposit Bytes  . *[B]dbtc           Deposit Bytes  . *[B]dbtp         ║
  13534.      ║ Deposit Time . . *[B]dtmc           Deposit Time . . *[B]dtmp         ║
  13535.      ║ Withdraw Bytes . *[B]wbtc           Withdraw Bytes . *[B]wbtp         ║
  13536.      ║ Withdraw Time  . *[B]wtmc           Withdraw Time  . *[B]wtmp         ║
  13537.      ║ Leave Bank Menu  *[B]lbmc           Bank Pause . . . *[B]bpap         ║
  13538.      ║ Logoff Bank Menu *[B]gbmc           Bank More  . . . *[B]bmop         ║
  13539.      ╟─┤ BBS File List Details ├───────────┤ BBS File List Details ├─────────╢
  13540.      ║ Catalog to Use . *[B]catl           Year Position  . *[B]fysp         ║
  13541.      ║ D/L Priority   > *[B]tdup           Date separator . *[B]dase         ║
  13542.      ║ Default Lst Area *[B]dfar           Comment Start  . *[B]fcsp         ║
  13543.      ║ Filename Start . *[B]fnsp           Comment End  . . *[B]fcep         ║
  13544.      ║ Extension Start  *[B]fesp           Continue Comment *[B]fcca         ║
  13545.      ║ Size Position  . *[B]fssp           Continue Comment *[B]fccb         ║
  13546.      ║ Month Position . *[B]fmsp           New File Area  . *[B]fcat         ║
  13547.      ║ Day Position . . *[B]fdsp           COUNT File Areas *[B]fnum         ║
  13548.      ╚═══════════════════════════════════════════════════════════════════════╝
  13549.  
  13550.      ╔═╡ File Commands ╞═══════════════════╡ File Prompts ╞══════════════════╗
  13551.      ║ Access File Menu *[F]afil           File Menu  . . . *[F]fmnp         ║
  13552.      ║ Default BBS Area *[F]fare           File Pause . . . *[F]fpap         ║
  13553.      ║ Area Change  . . *[F]facc           File More  . . . *[F]fmop         ║
  13554.      ║ New Files  . . . *[F]nflc           Enter D/L Fname  *[F]efip         ║
  13555.      ║ File Search  . . *[F]fsrc           Enter U/L Fname  *[F]efup         ║
  13556.      ║ Download File[s] *[F]fdlc           Enter Protocol . *[F]fprp         ║
  13557.      ║ Upload File[s] . *[F]fulc           Duplicate File . *[F]fdup         ║
  13558.      ║ Descrip @SCRIPT  *[F]edsc           Enter Descrip. . *[F]edsp         ║
  13559.      ║ Chars per Line . *[F]fcmx           File Not Found . *[F]fnfp         ║
  13560.      ║ Max Lines  . . . *[F]flmx           No Time  . . . . *[F]fitp         ║
  13561.      ║ Files per D/L  . *[F]fpbt           No Bytes . . . . *[F]fibp         ║
  13562.      ║ Files per U/L  . *[F]fpul           File Accepted  . *[F]fokp         ║
  13563.      ║ Batch Full Answr *[F]fbfc           Batch Full . . . *[F]fbfp         ║
  13564.      ║ File Password  . *[F]fepc           <Enter Password  *[F]feep         ║
  13565.      ║ Leave File Menu  *[F]lfmc           Download File[s] *[F]fdlp         ║
  13566.      ║ Logoff File Menu *[F]gfmc           Upload File[s] . *[F]fulp         ║
  13567.      ║ Upload PATH  . . *[F]upld           Transfer Abort . *[F]fabp         ║
  13568.      ║ Download Dir . . *[F]dnld           Transfer Okay  . *[F]fsup         ║
  13569.      ╚═══════════════════════════════════════════════════════════════════════╝
  13570.  
  13571.      ╔═╡ Extra Commands ╞══════════════════╡ Extra Prompts ╞═════════════════╗
  13572.      ║ External Extra A *[E]exac           External A . . . *[E]exap         ║
  13573.      ║ External Extra B *[E]exbc           External B . . . *[E]exbp         ║
  13574.      ║ External Extra C *[E]excc           External C . . . *[E]excp         ║
  13575.      ║ External Extra D *[E]exdc           External D . . . *[E]exdp         ║
  13576.      ║ Message Extra A  *[E]mxac           Message A  . . . *[E]mxap         ║
  13577.      ║ Message Extra B  *[E]mxbc           Message B  . . . *[E]mxbp         ║
  13578.      ║ Message Extra C  *[E]mxcc           Message C  . . . *[E]mxcp         ║
  13579.      ║ Message Extra D  *[E]mxdc           Message D  . . . *[E]mxdp         ║
  13580.      ║ File Extra A . . *[E]fxac           File A . . . . . *[E]fxap         ║
  13581.      ║ File Extra B . . *[E]fxbc           File B . . . . . *[E]fxbp         ║
  13582.      ║ File Extra C . . *[E]fxcc           File C . . . . . *[E]fxcp         ║
  13583.      ║ File Extra D . . *[E]fxdc           File D . . . . . *[E]fxdp         ║
  13584.      ╚═══════════════════════════════════════════════════════════════════════╝
  13585.  
  13586.  
  13587.  
  13588.  
  13589.      Intellicomm v2.01               SCRIPT.DOC                            216
  13590.      
  13591.      
  13592.  
  13593.                    C.  MAIN SETUP VARIABLES (Advanced Users Only)
  13594.  
  13595.      The Icom Main Setup Variables are used in the same way as the BIF
  13596.      Variables outlined above.  You must precede the variable's 'tag' name
  13597.      with an asterisk, and are free to use it as a parameter in any script
  13598.      command that takes a parameter.  However, the Main Setup Variables do not
  13599.      require a [S]ection as the BIF Variables do.  You simply specify an
  13600.      asterisk (*) followed by one of the main setup tags listed below. 
  13601.      Example:
  13602.  
  13603.       ;*swpon (swap on) is the default 'swapping' setting which determines
  13604.       ; whether Icom will swap itself out of memory when calling external
  13605.       ; programs
  13606.  
  13607.       variable s          ;define a variable called 's'
  13608.  
  13609.       if *swpon = 2 assign s "whether connected or not"
  13610.       if *swpon = 1 assign s "only if not connected"
  13611.       if *swpon = 0 assign s "NEVER"
  13612.  
  13613.       print "Icom will swap out of memory " s   ;note 's' following the text
  13614.  
  13615.      This would print one of the strings below:
  13616.  
  13617.       Icom will swap out of memory whether connected or not
  13618.       Icom will swap out of memory only if not connected
  13619.       Icom will swap out of memory NEVER
  13620.  
  13621.      For all of the on/off, yes/no settings, 1 means YES or ON, and 0 means NO
  13622.      or OFF.  To turn a setting ON, you'd ASSIGN 1 to it:
  13623.  
  13624.       ASSIGN *swpon 1         ;turn swapping on
  13625.       ASSIGN *swpon 0         ;turn swapping off
  13626.  
  13627.      Make sure you read the notes in the summaries of each variable below
  13628.      before you think about changing any of these variables in your scripts. 
  13629.      In many cases you will not get the results you expect without knowing all
  13630.      the details.  For example, *swpon can be overridden by the DOS command to
  13631.      execute by preceding the command with SW: (swap on) or NS: (swap off). 
  13632.      So if you had defined your Mail Reader (*mread Main Setup Variable) as
  13633.      SW:DELUXE.EXE in the main setup, changing *swpon would have no effect:
  13634.  
  13635.       ASSIGN *swpon 0         ;turn swapping OFF
  13636.       DOS *mread              ;same as DOS "SW:DELUXE.EXE" 
  13637.  
  13638.      Icom would swap itself out regardless, due to the SW: preceding the
  13639.      command.  In other cases, you may change a Main Setup Variable and find
  13640.      that it has no effect at all.  In many cases, by changing a Main Setup
  13641.      Variable, all you've done is changed the DEFAULT setting.  You may not
  13642.      have changed the variable Icom itself is working with.  For example, the
  13643.      $MSG_DIR System Variable holds the current Message Directory.  The
  13644.      directory in this variable is EITHER the Main Setup Variable (*msgdir) OR
  13645.      the BIF Variable (*[M]msgd) since you can override the Main Setup
  13646.      Variable with a setting in the BIF.  To change the variable that Icom is
  13647.  
  13648.  
  13649.  
  13650.  
  13651.      Intellicomm v2.01               SCRIPT.DOC                            217
  13652.      
  13653.      
  13654.  
  13655.      working with, you would change neither *msgdir nor *[M]msgd ... you'd
  13656.      change the $MSG_DIR System Variable.  Where this is the case, it will be
  13657.      pointed out in the summaries below, so be sure to see all the details
  13658.      before you set out working with these variables.
  13659.  
  13660.      NOTE: As with the BIF Variables, if you change a Main Setup Variable it
  13661.      does not change the .INI (INItialization) file on-disk.  It only changes
  13662.      the setting in MEMORY.  To save changes to disk you must use SAVEINI. 
  13663.      The $INI_NAME System Variable holds the filename of the currently loaded
  13664.      .INI (without the .INI extension).
  13665.  
  13666.      If you CHANGE any of the Main Setup Variables, you change the data that
  13667.      Icom is working with for the duration of the session (or until another
  13668.      .INI is loaded).  To avoid potential problems, you can either
  13669.      save/restore original INI data as we did above with the System Variables,
  13670.      or can simply use LOADINI $INI_NAME when your script ends, to re-load the
  13671.      original .INI and thus reset ALL the Main Setup Variables to their
  13672.      original values.  Until you're experienced with the FORMAT of the Main
  13673.      Setup Variables it is recommended that you do NOT change any of the main
  13674.      setup information.  To gain experience, use the normal Icom main setup
  13675.      menu to see what options go with a given item, then use the PRINT command
  13676.      (or simply view the ICOM.INI file in the File Viewer) to see how the
  13677.      options are represented.  Many options use NUMBERS to represent various
  13678.      options (0 means one thing, 1 means another 2 means something else, etc.,
  13679.      or 0 represents OFF while 1 represents ON for toggle items).  
  13680.  
  13681.      Note that several main setup variables will have no effect if you change
  13682.      them, until a SAVEINI / LOADINI is performed.  For example, if you change
  13683.      the *ssize (Screen Size) variable, the actual screen size will not change
  13684.      until a SAVEINI / LOADINI is performed.  LOADINI actually does the work
  13685.      of resetting Intellicomm with new values, but if you change main setup
  13686.      variables and use LOADINI *without* using SAVEINI first, you'll lose any
  13687.      changes you made to the main setup variables.  If you don't want to over-
  13688.      write the ICOM.INI file, do something like this:
  13689.  
  13690.       variable oldini $INI_NAME    ;SAVE original main setup filename
  13691.       ASSIGN *somevariable "Some value"
  13692.       ...
  13693.  
  13694.       SAVEINI "$TEMP"              ;save new values to a temporary INI file
  13695.       LOADINI "$TEMP"              ;load the temporary INI file to reset Icom
  13696.  
  13697.       ...                          ;main body of script goes here
  13698.  
  13699.       LOADINI oldini               ;reset with the usual values
  13700.       DELETE $HOME_DIR "$TEMP.INI" ;you can delete the file before your script
  13701.                                    ; exits, as long as you load another INI
  13702.                                    ; file first
  13703.  
  13704.  
  13705.  
  13706.  
  13707.      Intellicomm v2.01               SCRIPT.DOC                            218
  13708.      
  13709.      
  13710.  
  13711.      ╔═╡ User Settings ╞═════════════════════════════════════╗
  13712.      ║ Alt-1  First Last Name : *uname                       ║
  13713.      ║ Alt-2  BBS Password    : $PASSWORD                    ║
  13714.      ║ Alt-3  Street Address  : *uaddr                       ║
  13715.      ║ Alt-4  City, State/Prov: *ucity                       ║
  13716.      ║ Alt-5  ZIP/Postal Code : *uzip                        ║
  13717.      ║ Alt-6  Business Phone #: *ubphn                       ║
  13718.      ║ Alt-7  Home Phone #    : *uhphn                       ║
  13719.      ║ Alt-8  Date of Birth   : *udtob                       ║
  13720.      ║ Alt-9  General Use     : *alt9                        ║
  13721.      ║ Alt-0  General Use     : *alt0                        ║
  13722.      ╚═══════════════════════════════════════════════════════╝
  13723.  
  13724.      ╔═╡ General Settings ╞══════════════════════════════════╗
  13725.      ║ Password Access Key . . . N/A                         ║
  13726.      ║ Base and Startup Area . . *sarea                      ║
  13727.      ║ TAB / Shift-TAB moves the *swptab                     ║
  13728.      ║ Put Overlays in XMS/EMS . *overlay                    ║
  13729.      ║ Enable Swapping . . . . . *swpon                      ║
  13730.      ║ Release Time Slices?  . . *rslice                     ║
  13731.      ║ Drop RTS on Disk I/O? . . *droprts                    ║
  13732.      ║ Mouse Settings  . . . . . *mouse (see below)          ║
  13733.      ║ Use PATH to Locate Files  *pathsch                    ║
  13734.      ║ File Renumber Mode  . . . *rmode                      ║
  13735.      ║ Usage Log Renumber Total  *usenum                     ║
  13736.      ║ Capture Renumber Total  . *capnum                     ║
  13737.      ║ Message Renumber Total  . *msgnum                     ║
  13738.      ║ Reply Renumber Total  . . *repnum                     ║
  13739.      ║ Auto-Open Usage Log . . . *useopen                    ║
  13740.      ║ Open Capture on Connect . *capopen                    ║
  13741.      ║ Stamp Date/Time Cap Open  *capstamp                   ║
  13742.      ║ Sound . . . . . . . . . . *sound                      ║
  13743.      ║ Pager . . . . . . . . . . *pager                      ║
  13744.      ║ Date Format . . . . . . . *date                       ║
  13745.      ║ Date Separator  . . . . . *datesep                    ║
  13746.      ║ Time Format . . . . . . . *time                       ║
  13747.      ║ Time Separator  . . . . . *timesep                    ║
  13748.      ╚═══════════════════════════════════════════════════════╝ 
  13749.  
  13750.      Mouse Mode : 0=Off 1=Righthanded 2=Lefthanded
  13751.      Mouse Speed: not adjustable from scripts.
  13752.                                                               
  13753.      ╔═╡ Filenames and Paths ╞═══════════════════════════════╗
  13754.      ║ Mail Reader> *mread                                   ║
  13755.      ║ Reply Dir  > *repdir                                  ║
  13756.      ║ Message Dir> *msgdir                                  ║
  13757.      ║ Main Unpack> *unpak1                                  ║
  13758.      ║ 2nd  Unpack> *unpak2                                  ║
  13759.      ║ Arc. Viewer> *zipview                                 ║
  13760.      ║ File Viewer  *flister                                 ║
  13761.      ║ Extnl Editor *editor                                  ║
  13762.      ║ Alt-N Hotkey *hkey1c                                  ║
  13763.      ║  Description *hkey1t                                  ║
  13764.      ║ Alt-O Hotkey *hkey2c                                  ║
  13765.  
  13766.  
  13767.  
  13768.  
  13769.      Intellicomm v2.01               SCRIPT.DOC                            219
  13770.      
  13771.      
  13772.  
  13773.      ║  Description *hkey2t                                  ║
  13774.      ║ BIF Dir  . . *lbif                                    ║
  13775.      ║ Catalog Dir  *dbfpath                                 ║
  13776.      ║ Filelist Dir *lstdir                                  ║
  13777.      ║ Upload PATH  *updir                                   ║
  13778.      ║ Download Dir *dldir                                   ║
  13779.      ║ Script Dir . *scrdir                                  ║
  13780.      ║ Usage Log  . *usefile                                 ║
  13781.      ║ Capture File *capfile                                 ║
  13782.      ║ Screen Cap . *scap                                    ║
  13783.      ║ Swap Dir . . *swpdir                                  ║
  13784.      ║ Printer  . . *prn                                     ║
  13785.      ╚═══════════════════════════════════════════════════════╝
  13786.  
  13787.      ╔═╡ Screen/Color Settings ╞═════════════════════════════╗
  13788.      ║ Menu Style/Colors . . . . (See below)                 ║
  13789.      ║ Default Screen Size . . . *ssize                      ║
  13790.      ║ Screen Write Mode . . . . *vmode                      ║
  13791.      ║ Blank Screen # Seconds  . *scrblank                   ║
  13792.      ║ Status Window Delay . . . *sdelay                     ║
  13793.      ╚═══════════════════════════════════════════════════════╝
  13794.  
  13795.      ╔═╡ Screen/Color Settings ╞═════════════════════════════╗
  13796.      ║ Menu Style            *bstyle                         ║
  13797.      ║ Border                *border                         ║
  13798.      ║ Selected/Hilit        *bar                            ║
  13799.      ║ Unselected/background *norm                           ║
  13800.      ║ Bold/Hotkey           *bold                           ║
  13801.      ║ Terminal              *tcolor                         ║
  13802.      ║ Status Line           *scolor                         ║
  13803.      ╚═══════════════════════════════════════════════════════╝
  13804.                                          
  13805.      ╔═╡ Debugging Log Settings ╞════════════════════════════╗
  13806.      ║ Debugging Level . . . . . *dbglevel                   ║
  13807.      ║ Debugging Log Filename. . *dbgfname                   ║
  13808.      ║ Log Renumber Total  . . . *dbgnum                     ║
  13809.      ╚═══════════════════════════════════════════════════════╝
  13810.  
  13811.      ╔═╡ Sysop Settings ╞════════════════════════════════════╗
  13812.      ║ Export D/L's to TEXT FILE *xfile                      ║
  13813.      ║ Export by ID/Conference?  *xconf                      ║
  13814.      ║ BIF Format for Export . . *xbif                       ║
  13815.      ║ Move files to Subdir  . . *msdir                      ║
  13816.      ╚═══════════════════════════════════════════════════════╝
  13817.                                             
  13818.      ╔═╡ Terminal Settings ╞═════════════════════════════════╗
  13819.      ║ Default Comm. Port      > *port                       ║
  13820.      ║ Default Port Settings   > *csettings                  ║
  13821.      ║ Software Flow Control   > *flowctrl (see below)       ║
  13822.      ║ Hardware Flow Control   > *flowctrl (see below)       ║
  13823.      ║ Initialize Modem String > *minit                      ║
  13824.      ║ Modem Hangup String     > *mhang                      ║
  13825.      ║ Confirm Hangup? . . . . . *hconfirm                   ║
  13826.      ║ Drop DTR to Hangup? . . . *dtrhangup                  ║
  13827.  
  13828.  
  13829.  
  13830.  
  13831.      Intellicomm v2.01               SCRIPT.DOC                            220
  13832.      
  13833.      
  13834.  
  13835.      ║ Init Modem at Startup?  . *istart                     ║
  13836.      ║ Init Modem if Connected?  *cdinit                     ║
  13837.      ║ Status Bar  . . . . . . . *statbar                    ║
  13838.      ║ Status Bar Displays . . . *statbarsp                  ║
  13839.      ║ Scrollback Size [Kbytes]  *sbsize                     ║
  13840.      ║ Receive Buffer Size [K] . *rxbuf                      ║
  13841.      ║ Transmit Buffer Size [K]  *txbuf                      ║
  13842.      ║ Echo  . . . . . . . . . . *echo                       ║
  13843.      ║ Add Line Feeds  . . . . . *addlf                      ║
  13844.      ║ Backspace Destructive?  . *bsdest                     ║
  13845.      ║ Send DEL as Backspace?  . *bsswap                     ║
  13846.      ║ Enable 16550 if Found?  . *16550fl                    ║
  13847.      ║ 16550 Receive Trigger . . *16550rx                    ║
  13848.      ║ 16550 Transmit Trigger  . *16550tx                    ║
  13849.      ║ ENQ Response/@SCRIPT  . . *enqstr                     ║
  13850.      ╚═══════════════════════════════════════════════════════╝
  13851.  
  13852.      *flowctrl: ADD the following values;
  13853.       0 = No flow control
  13854.       1 = XON/XOFF
  13855.       2 = XON=any char/XOFF
  13856.       4 = CTS/RTS
  13857.       8 = DSR/DTR
  13858.      EXAMPLES:
  13859.       ASSIGN *flowctrl 1   ;XON/XOFF only
  13860.       ASSIGN *flowctrl 4   ;CTS/RTS only
  13861.       ASSIGN *flowctrl 5   ;XON/XOFF and CTS/RTS (1 + 4)
  13862.      You must use a 'PORT $COM_PORT' command (re-open the current COM port)
  13863.      for changes to *flowctrl to take effect.
  13864.  
  13865.      ╔═╡ Dialer Settings ╞═══════════════════════════════════╗
  13866.      ║ Dial Prefix 1           > *dpre1                      ║
  13867.      ║ Dial Prefix 2 . . . . . . *dpre2                      ║
  13868.      ║ Dial Prefix 3 . . . . . . *dpre3                      ║
  13869.      ║ ! Dial Code . . . . . . . *dcode!                     ║
  13870.      ║ @ Dial Code . . . . . . . *dcode@                     ║
  13871.      ║ $ Dial Code . . . . . . . *dcode$                     ║
  13872.      ║ Dial Suffix . . . . . . . *dsuff                      ║
  13873.      ║ Dial Connected          > *dconnect                   ║
  13874.      ║ Minimum CONNECT Speed   > *minspeed                   ║
  13875.      ║ Auto Baud Adjustment    > *baudetect                  ║
  13876.      ║ Dial Busy/Retry 1       > *dagain1                    ║
  13877.      ║ Dial Busy/Retry 2       > *dagain2                    ║
  13878.      ║ Dial Busy/Retry 3       > *dagain3                    ║
  13879.      ║ Exclude Dialing 1       > *dabort1                    ║
  13880.      ║ Exclude Dialing 2       > *dabort2                    ║
  13881.      ║ Exclude Dialing 3       > *dabort3                    ║
  13882.      ║ Dial Timeout  . . . . . . *dtime                      ║
  13883.      ║ Stop Dialing  . . . . . . *dstop                      ║
  13884.      ║ Pause Between Dials . . . *dpause                     ║
  13885.      ║ Attempts per BIF/Cycle  . *dcycle                     ║
  13886.      ║ LD Service Phone Num  . . *ldnum                      ║
  13887.      ╚═══════════════════════════════════════════════════════╝
  13888.                                              
  13889.  
  13890.  
  13891.  
  13892.  
  13893.      Intellicomm v2.01               SCRIPT.DOC                            221
  13894.      
  13895.      
  13896.  
  13897.      ╔═╡ File Transfer Settings ╞════════════════════════════╗
  13898.      ║ POSTFILE.SCR Settings     (See below)                 ║
  13899.      ║ Move Old Downloads?     > *dlmove                     ║
  13900.      ║ Cancel D/L No Time/Bytes  *candl                      ║
  13901.      ║ Auto Zmodem Receive . . . *zauto                      ║
  13902.      ║ Auto Zmodem Protocol  . . *zprotocol                  ║
  13903.      ║ Zmodem Crash Recovery . . *zrresume                   ║
  13904.      ║ Filename Conversion . . . *fconv                      ║
  13905.      ║ Manage Duplicate Files  . *fmanage                    ║
  13906.      ║ Delete Aborted Transfers  *delabort                   ║
  13907.      ║ Disk Buffer Size [Kbytes] *xdbufsiz                   ║
  13908.      ║ ASCII Transfers . . . . . (See table below)           ║
  13909.      ╚═══════════════════════════════════════════════════════╝
  13910.  
  13911.      POSTFILE.SCR Settings: Settings for POSTFILE.SCR are stored in
  13912.      $SCRIPT_DIR\POSTFILE.INI.  This is a straight ASCII text file that stores
  13913.      one setting per line, and the file can be read and/or modified with a
  13914.      script if necessary.  See POSTINI.SCR for details; look for FOPEN, FGETS
  13915.      and FPUTS commands.  These read and write to POSTINI.SCR just as you can
  13916.      do in your own scripts.  Do not add any new settings to POSTFILE.INI,
  13917.      however, nor change the order in which the items are stored.
  13918.  
  13919.      ASCII Transfers:                                               
  13920.      ╔═╡ ASCII Transfer Details ╞════════════════════════════╗
  13921.      ║ Line Pacing/Delay [tenths] *alpace                    ║
  13922.      ║ Char Pacing/Delay [tenths] *acpace                    ║
  13923.      ║ Receive Timeout  [seconds] *atmout                    ║
  13924.      ╚═══════════════════════════════════════════════════════╝
  13925.                                                     
  13926.      ╔═╡ External Protocols ╞════════════════════════════════╗
  13927.      ║                                                       ║
  13928.      ║      Descrip  Hotkey  Receive  Send Cmd.  Ask?        ║
  13929.      ║                                                       ║
  13930.      ║  1.  *prot1n  *prot1k *prot1r  *prot1s    *prot1f     ║
  13931.      ║  2.  *prot2n  *prot2k *prot2r  *prot2s    *prot2f     ║
  13932.      ║  3.  *prot3n  *prot3k *prot3r  *prot3s    *prot3f     ║
  13933.      ║  etc... up to 8                                       ║
  13934.      ╚═══════════════════════════════════════════════════════╝ 
  13935.  
  13936.      ╔═╡ Host Mode Settings ╞════════════════════════════════╗
  13937.      ║ Sysop Name  . . . . . . . *hsysop                     ║
  13938.      ║ Host Download Dir . . . . *hdldir                     ║
  13939.      ║ Host Upload Dir . . . . . *huldir                     ║
  13940.      ║ Level 1 Password  . . . . (See below)                 ║
  13941.      ║ Level 2 Password  . . . . (See below)                 ║
  13942.      ║ DOS Shell Password  . . . (See below)                 ║
  13943.      ║ Abort Host Password . . . (See below)                 ║
  13944.      ║ Modem Init Host Command . *hminit                     ║
  13945.      ║ Modem Offhook Command . . *hoffhook                   ║
  13946.      ║ Modem Answer Command  . . *manswer                    ║
  13947.      ║ Modem OK Message  . . . . *mokay                      ║
  13948.      ║ Modem RING Message  . . . *mring                      ║
  13949.      ║ Answer on Ring #  . . . . *hrings                     ║
  13950.      ║ Main Setup File for Host  *hini                       ║
  13951.  
  13952.  
  13953.  
  13954.  
  13955.      Intellicomm v2.01               SCRIPT.DOC                            222
  13956.      
  13957.      
  13958.  
  13959.      ║ Level 1 can OVERWRITE?  . *hoverwrite (0=No; 1=Yes    ║
  13960.      ║ Level 1 EXTNL Protocols?  *hextp (0=No; 1=Yes)        ║
  13961.      ║ Direct CABLE Link?  . . . *hcable (0=Modem; 1=Cable)  ║
  13962.      ╚═══════════════════════════════════════════════════════╝ 
  13963.  
  13964.      The host passwords are stored separately in the file $HOME_DIR\HOST.PWD. 
  13965.      This is a straight ASCII text file and each password is stored on a
  13966.      separate line.  To read the passwords:
  13967.  
  13968.      variable pass1
  13969.      variable pass2
  13970.      variable dospass
  13971.      variable abortpass
  13972.      variable f $HOME_DIR "HOST.PWD"
  13973.  
  13974.      fopen f f "r"                  ;open in read mode
  13975.      fgets pass1 f                  ;Level 1 Password
  13976.      fgets pass2 f                  ;Level 2 Password
  13977.      fgets dospass f                ;DOS Shell Password
  13978.      fgets abortpass f              ;Abort Host Password
  13979.      fclose f                       ;close HOST.PWD
  13980.  
  13981.      To write new passwords to disk, replace "r" (read) in the FOPEN command
  13982.      with "w" (write), and replace the four FGETS commands with FPUTS.  Note
  13983.      that FPUTS reverses the order of the variable and the file handle:
  13984.  
  13985.      fputs f pass1                  ;file handle first
  13986.  
  13987.      ╔═╡ Comm Port Settings ╞════════════════════════════════╗
  13988.      ║ COM1 Base Address . . . . *com1b                      ║
  13989.      ║      IRQ Line . . . . . . *com1i                      ║
  13990.      ║ COM2 Base Address . . . . *com2b                      ║
  13991.      ║      IRQ Line . . . . . . *com2i                      ║
  13992.      ║ COM3 Base Address . . . . *com3b                      ║
  13993.      ║      IRQ Line . . . . . . *com3i                      ║
  13994.      ║ etc... up to 8                                        ║
  13995.      ╚═══════════════════════════════════════════════════════╝
  13996.  
  13997.      You must use a 'PORT' command (re-open the current COM port) for changes
  13998.      to *com?b / *com?i to take effect.
  13999.                                                               
  14000.      ╔═╡ File Tagger Settings ╞══════════════════════════════╗
  14001.      ║ File Transfer Speed [CPS] *acps                       ║
  14002.      ║ Tagger Screen Size  . . . *tssize                     ║
  14003.      ║ Description Lines Shown . *split                      ║
  14004.      ║ Auto Hilight Bar Lock . . *ahlock                     ║
  14005.      ║ View Date Filters Noted?  *fnote                      ║
  14006.      ║ Duplicate Checking  . . . *ckdupe                     ║
  14007.      ║ Use DOWNLOAD.NDX  . . . . *dndx                       ║
  14008.      ║ File .EXTensions in DNDX  *dndxext                    ║
  14009.      ║ DOWNLOAD.NDX Directories  Stored in file DNDX.DIR     ║
  14010.      ║ Filter Graphics Chars . . *fgraph                     ║
  14011.      ║ Replace Shorter Comments  *ckcmts                     ║
  14012.      ║ Extract NEWFILES / mail . *qwknew                     ║
  14013.  
  14014.  
  14015.  
  14016.  
  14017.      Intellicomm v2.01               SCRIPT.DOC                            223
  14018.      
  14019.      
  14020.  
  14021.      ║ Auto Import New Files . . *taguse                     ║
  14022.      ║ Keep an Upload Catalog  . *tagimpt                    ║
  14023.      ║ Purge Noted # Days Old  . *prgnote                    ║
  14024.      ║ Purge Untagged # Days Old *purge                      ║
  14025.      ║ Auto Pack when # Purged . *ppack                      ║
  14026.      ║ Auto Bookmark Update  . . *abook                      ║
  14027.      ║ Auto View Date Update . . *afdate                     ║
  14028.      ╚═══════════════════════════════════════════════════════╝
  14029.                                                         
  14030.      ╔═╡ Tagger Keywords ╞═══════════════════════════════════╗
  14031.      ║ Strip Comment Keywords  . Stored in file STRIP.KWD    ║
  14032.      ║ Replace Word(s) Keywords  Stored in file REPLACE.KWD  ║
  14033.      ║ Exclude File Keywords . . Stored in file EXCLUDE.KWD  ║
  14034.      ║ Note File Keywords  . . . Stored in file NOTE.KWD     ║
  14035.      ║ Auto Tag Remaining Files? *atag                       ║
  14036.      ╚═══════════════════════════════════════════════════════╝
  14037.  
  14038.  
  14039.  
  14040.  
  14041.      Intellicomm v2.01               SCRIPT.DOC                            224
  14042.      
  14043.      
  14044.  
  14045.                                   D.  COLOR CODES
  14046.  
  14047.  
  14048.      Using the codes below, you can create your own colors for use with the
  14049.      SCROLL (scroll or clear an area of the screen) and PRINTRAW commands
  14050.      (print directly to the screen in a specific color).  You can also assign
  14051.      custom colors to the color variables Icom uses: $NORM_COLOR, $BOLD_COLOR,
  14052.      $BORDER_COLOR, etc., to draw menus (BARMENU, etc) and boxes (BOX).
  14053.  
  14054.      If your script is going to be used by others (if you intend to upload it
  14055.      to a BBS later, etc.) it is recommended that you do NOT use custom colors
  14056.      in your script at all.  Laptop and monochrome displays cannot display all
  14057.      colors properly, so even if your script looks pretty on your screen, it
  14058.      is possible that it will be unreadable on someone else's screen.  By
  14059.      using $BAR_COLOR, $BORDER_COLOR, $NORM_COLOR, $TERM_COLOR, $STAT_COLOR
  14060.      (see the System Variables appendix above for details) you can use the
  14061.      colors that the USER has set up in Intellicomm.  This will give your
  14062.      script an integrated look with Intellicomm, and whenever the user changes
  14063.      colors in the Icom main setup, your script will also make use of the new
  14064.      colors!
  14065.  
  14066.      To create a custom color first pick your background color from the table
  14067.      below (the number of the color).  Background colors can be ONLY the
  14068.      colors listed in the first column of the table (0-7).  If you try to use
  14069.      a background color above 7, the foreground color will BLINK.  Once you
  14070.      have your background color, multiply it by 16, then add the foreground
  14071.      color.  Any of the 16 colors (0-15) may be used for a foreground color. 
  14072.      The formula to create a color (and the background color limitation of
  14073.      using only 0-7) has nothing to do with the script language; it's simply
  14074.      how IBM video adaptors work.  The formula is (with 'x' representing
  14075.      multiplication):
  14076.  
  14077.                         COLOR = background x 16 + foreground
  14078.  
  14079.                        0  Black               8 Dark Gray
  14080.                        1  Blue                9 Light Blue
  14081.                        2  Green              10 Light Green
  14082.                        3  Cyan               11 Light Cyan
  14083.                        4  Red                12 Light Red
  14084.                        5  Magenta            13 Light Magenta
  14085.                        6  Brown              14 Yellow
  14086.                        7  Light Gray         15 White
  14087.  
  14088.                                   +128  Blink
  14089.  
  14090.      For example, to display white foreground text on a red background you'd
  14091.      multiply 4 (Red) by 16, then add 15 (White).  The number you come up with
  14092.      (79) could then be used in PRINTRAW and SCROLL commands, or could be
  14093.      ASSIGNed to the various COLOR System Variables to change the colors Icom
  14094.      uses with the BOX, BOXGETS, MENUBAR, etc. commands.  With PRINTRAW the
  14095.      color is the 3rd parameter:
  14096.  
  14097.        PRINTRAW $SCRN_X $SCRN_Y 79 "White text on a red background"
  14098.  
  14099.  
  14100.  
  14101.  
  14102.      Intellicomm v2.01               SCRIPT.DOC                            225
  14103.      
  14104.      
  14105.  
  14106.      To make the foreground text blink on and off, just add 128 to the
  14107.      original color value (79 + 128 = 207):
  14108.  
  14109.       PRINTRAW 1 1 207 "White blinking text on a red background"
  14110.  
  14111.      D.1  Using Color Variables
  14112.  
  14113.      If you intend to use custom colors in your script, you still might want
  14114.      to use variables to specify colors, instead of specifying color values in
  14115.      individual SCROLL/PRINTRAW/CLS, etc. commands.  Example:
  14116.  
  14117.        VARIABLE color1 7  ;gray on black
  14118.        VARIABLE color2 23 ;light gray on blue
  14119.  
  14120.          ;now, use these color variables in the rest of the script
  14121.  
  14122.        PRINTRAW 1 1 color1 "Some text"
  14123.        CLS color2
  14124.        ...etc.
  14125.  
  14126.      Then, if you want to change the colors later all you'll have to do is
  14127.      change the color assigned to the variables (make one change), instead of
  14128.      having to change each individual color code in the commands themselves.  
  14129.  
  14130.      Alternatively, you can simply ASSIGN new color codes to the usual Icom
  14131.      color variables, then use BOXGETS, the MENUXXXX commands, WNDOPEN, PRINT,
  14132.      etc (which all use the regular $XXXX_COLOR variables).  Just make sure to
  14133.      save the old color values and restore them when your script exits:
  14134.  
  14135.       VARIABLE old_norm_color $NORM_COLOR  ;save existing color values
  14136.       VARIABLE old_border_color $BORDER_COLOR
  14137.  
  14138.       ASSIGN $NORM_COLOR 112   ;black on light gray (semi-paper white)
  14139.       ASSIGN $BORDER_COLOR 31  ;white on blue
  14140.  
  14141.       WNDOPEN "Window Border is White on Blue"
  14142.       PRINT "Text in window is Black on White"
  14143.  
  14144.       ASSIGN $NORM_COLOR old_norm_color      ;restore original values
  14145.       ASSIGN $BORDER_COLOR old_border_color
  14146.  
  14147.  
  14148.                                   E.  ASCII CODES
  14149.  
  14150.  
  14151.      ASCII stands for "American Standard Code for Information Interchange",
  14152.      and the ASCII character set is what lets our computers display things on-
  14153.      screen and print things such as this document.  Computers understand one
  14154.      thing, and one thing only: numbers.  They don't understand the letters
  14155.      numbers or symbols we humans use, so someone had to assign numbers to all
  14156.      the characters and symbols, so that computers could display and print
  14157.      characters that we humans use.  The ASCII codes listed below are the
  14158.      numeric equivalent of characters/symbols that most all personal computers
  14159.      use.
  14160.  
  14161.  
  14162.  
  14163.  
  14164.      Intellicomm v2.01               SCRIPT.DOC                            226
  14165.      
  14166.      
  14167.  
  14168.      E.1  How to Use the ASCII Table
  14169.  
  14170.      The numbers listed in the 'Num' column below are the ASCII codes for all
  14171.      the characters, and are for use only with the SENDKEY command.  SENDKEY
  14172.      32 is equivalent to SENDNC " " (send a space; SENDNC doesn't add a CR as
  14173.      SEND does).  SENDKEY 8 sends a backspace (BS) to the BBS, SENDKEY 65
  14174.      sends the letter "A" (see the extended keycodes in the next section for
  14175.      more).
  14176.  
  14177.      The characters listed in the 'Char' column are the character equivalents,
  14178.      which can be used in any script 'string' (between quotes).  To send a
  14179.      Ctrl-C to the BBS you'd use SENDNC "^C".  To send two ESC character you'd
  14180.      use SENDNC "^[^[", etc.  The "Name" column (control characters) is for
  14181.      reference only.  You cannot use SEND ESC to send an ESC character.
  14182.  
  14183.                 Num Char Name    Num Char     Num Char     Num Char
  14184.                 -------------    --------     --------     --------
  14185.                  0   ^@  NUL      32           64    @      96    `
  14186.                  1   ^A  SOH      33    !      65    A      97    a
  14187.                  2   ^B  STX      34    "      66    B      98    b
  14188.                  3   ^C  ETX      35    #      67    C      99    c
  14189.                  4   ^D  EOT      36    $      68    D     100    d
  14190.                  5   ^E  ENQ      37    %      69    E     101    e
  14191.                  6   ^F  ACK      38    &      70    F     102    f
  14192.                  7   ^G  BEL      39    '      71    G     103    g
  14193.                  8   ^H  BS       40    (      72    H     104    h
  14194.                  9   ^I  HT       41    )      73    I     105    i
  14195.                 10   ^J  LF       42    *      74    J     106    j
  14196.                 11   ^K  VT       43    +      75    K     107    k
  14197.                 12   ^L  FF       44    ,      76    L     108    l
  14198.                 13   ^M  CR       45    -      77    M     109    m
  14199.                 14   ^N  SO       46    .      78    N     110    n
  14200.                 15   ^O  SI       47    /      79    O     111    o
  14201.                 16   ^P  DLE      48    0      80    P     112    p
  14202.                 17   ^Q  DC1      49    1      81    Q     113    q
  14203.                 18   ^R  DC2      50    2      82    R     114    r
  14204.                 19   ^S  DC3      51    3      83    S     115    s
  14205.                 20   ^T  DC4      52    4      84    T     116    t
  14206.                 21   ^U  NAK      53    5      85    U     117    u
  14207.                 22   ^V  SYN      54    6      86    V     118    v
  14208.                 23   ^W  ETB      55    7      87    W     119    w
  14209.                 24   ^X  CAN      56    8      88    X     120    x
  14210.                 25   ^Y  EM       57    9      89    Y     121    y
  14211.                 26   ^Z  SUB      58    :      90    Z     122    z
  14212.                 27   ^[  ESC      59    ;      91    [     123    {
  14213.                 28   ^\  FS       60    <      92    \     124    |
  14214.                 29   ^]  GS       61    =      93    ]     125    }
  14215.                 30   ^^  RS       62    >      94    ^     126    ~
  14216.                 31   ^_  US       63    ?      95    _     127   DEL
  14217.  
  14218.      IBM enhanced the standard ASCII set and added the characters in the next
  14219.      table below.  To enter these characters in a "string" in a script, hold
  14220.      down your [Alt] key, then enter the number in the 'Num' column on the
  14221.      NUMERIC KEYPAD, and release the [Alt] key (don't use the numbers at the
  14222.  
  14223.  
  14224.  
  14225.  
  14226.      Intellicomm v2.01               SCRIPT.DOC                            227
  14227.      
  14228.      
  14229.  
  14230.      top of the keyboard... they don't work).  For example, to enter this
  14231.      command in a script:
  14232.  
  14233.      print "Ç"
  14234.  
  14235.      type 'print"', and while holding down the [Alt] key, press [1], [2], [8] 
  14236.      (character 128 is Ç) on the NUMERIC KEYPAD, release the [Alt] key (the Ç
  14237.      will then then be inserted), then enter the trailing quote (").
  14238.  
  14239.      To send extended characters out the COM port, either use the same
  14240.      technique above with SEND or SENCNC, or use the number of the character
  14241.      (the 'Num' column below) with SENDKEY.  E.g., SENDKEY 128 sends Ç.
  14242.  
  14243.      This table may not be printed properly if your printer can't handle
  14244.      extended ASCII characters:
  14245.  
  14246.                 Num Char     Num Char     Num Char     Num Char
  14247.                 --------     --------     --------     --------
  14248.                 128   Ç      144   É      192   └      208   ╨ 
  14249.                 129   ü      145   æ      193   ┴      209   ╤ 
  14250.                 130   é      146   Æ      194   ┬      210   ╥ 
  14251.                 131   â      147   ô      195   ├      211   ╙ 
  14252.                 132   ä      148   ö      196   ─      212   ╘ 
  14253.                 133   à      149   ò      197   ┼      213   ╒ 
  14254.                 134   å      150   û      198   ╞      214   ╓ 
  14255.                 135   ç      151   ù      199   ╟      215   ╫ 
  14256.                 136   ê      152   ÿ      200   ╚      216   ╪ 
  14257.                 137   ë      153   Ö      201   ╔      217   ┘ 
  14258.                 138   è      154   Ü      202   ╩      218   ┌ 
  14259.                 139   ï      155   ¢      203   ╦      219   █ 
  14260.                 140   î      156   £      204   ╠      220   ▄ 
  14261.                 141   Ä      157   ¥      205   ═      221   ▌ 
  14262.                 142   Ä      158   ₧      206   ╬      222   ▐ 
  14263.                 143   Å      159   ƒ      207   ╧      223   ▀ 
  14264.                 160   á      176   ░      224   α      240   ≡
  14265.                 161   í      177   ▒      225   ß      241   ±
  14266.                 162   ó      178   ▓      226   Γ      242   ≥
  14267.                 163   ú      179   │      227   π      243   ≤
  14268.                 164   ñ      180   ┤      228   Σ      244   ⌠
  14269.                 165   Ñ      181   ╡      229   σ      245   ⌡
  14270.                 166   ª      182   ╢      230   µ      246   ÷
  14271.                 167   º      183   ╖      231   τ      247   ≈
  14272.                 168   ¿      184   ╕      232   Φ      248   Φ
  14273.                 169   ⌐      185   ╣      233   Θ      249   Θ
  14274.                 170   ¬      186   ║      234   Ω      250   Ω
  14275.                 171   ½      187   ╗      235   δ      251   √
  14276.                 172   ¼      188   ╝      236   ∞      252    
  14277.                 173   ¡      189   ╜      237   φ      253   ²
  14278.                 174   «      190   ╛      238   ε      254   ■
  14279.                 175   »      191   ┐      239   ∩      255   
  14280.  
  14281.  
  14282.  
  14283.  
  14284.      Intellicomm v2.01               SCRIPT.DOC                            228
  14285.      
  14286.      
  14287.  
  14288.                                  F.  KEYBOARD CODES
  14289.  
  14290.      As with the characters computers display on the screen (see ASCII codes
  14291.      above), computers are unable to understand what an [A] or [B] is, since
  14292.      computers understand numbers and only numbers.  So again, someone had to
  14293.      assign numbers to all the keys on the keyboard, and the various
  14294.      combinations of key presses such as [Alt-A], [Shift-F1] so that the
  14295.      computer could understand various key presses, and separate one key from
  14296.      another.  Intellicomm's script processor does recognize text for the
  14297.      standard keys (you needn't deal with numbers to check for an [A] key
  14298.      press for example), but text equivalents are not available for most of
  14299.      the extended keys such as [Alt-A], [F1], etc.  The tables below list the
  14300.      text equivalents of various key presses (where available) or the NUMBER
  14301.      of the key press where a text equivalent is not available.  You'll need
  14302.      these keyboard codes for semi-advanced script projects where you need
  14303.      direct control over the keyboard.
  14304.  
  14305.      F.1  How to use the Keyboard Codes
  14306.  
  14307.      The tables below list all keys on a standard IBM XT or enhanced (101 key)
  14308.      AT keyboard.  Note that the [F11] and [F12] function keys are only
  14309.      available on AT keyboards, so avoid using these two keys if you'll be
  14310.      distributing your script to the general public.
  14311.  
  14312.      The 'Key' column lists the actual key, the 'Norm' column lists the code
  14313.      of the key when pressed alone (without [Shift], [Ctrl] or [Alt]), the
  14314.      'Shift' column lists the code of the key when pressed in combination with
  14315.      either the left or right [Shift] key, the 'Ctrl' column lists the code of
  14316.      the key when pressed in combination with either the left or right [Ctrl]
  14317.      key,  and the 'Alt' column lists the code of the key when pressed in
  14318.      combination with either the left or right [Alt] key.
  14319.  
  14320.      The most common use of these tables is for use with the INKEY, INKEYW
  14321.      INKEYT and SENDKEY commands, or with the $HOTKEY_? variables.  The
  14322.      numbers and/or characters in the tables below show you how to check or
  14323.      specify a given key press.  Examples follow.
  14324.  
  14325.      Regular key presses (with a value below 255... keys in the standard ASCII
  14326.      code set) are always specified as a regular character between double
  14327.      quotes ("A", "B", "C", etc).  Common control characters such as [Ctrl-A],
  14328.      [Ctrl-B], [Ctrl-C] are specified as a regular character preceded by a
  14329.      caret (^), between double quotes ("^A", "^B", "^C").  Extended key
  14330.      presses are always specified as a number WITHOUT double quotes ([Alt-A]
  14331.      for example is key code 7680).
  14332.  
  14333.      Note that if $KEY_CHECK is non-zero (non-zero means $KEY_CHECK is ON),
  14334.      Intellicomm's script processor and Icom's Terminal will 'eat' many
  14335.      extended key codes.  For example, [Alt-A] is the standard Icom key to
  14336.      enter the Text Editor; in order to use [Alt-A] in your script you should
  14337.      set the $KEY_CHECK variable to zero before using INKEY / INKEYW / INKEYT:
  14338.  
  14339.       variable code
  14340.       variable old_kcheck $KEY_CHECK     ;save original value
  14341.       assign $KEY_CHECK 0                ;set to 0 to check for extended key
  14342.  
  14343.  
  14344.  
  14345.  
  14346.      Intellicomm v2.01               SCRIPT.DOC                            229
  14347.      
  14348.      
  14349.  
  14350.                                          ; codes
  14351.       
  14352.       printnc "Press a key: "
  14353.       inkeyw code                        ;stores the key code in variable
  14354.                                          ; 'code'
  14355.  
  14356.       print "^M^JKey code is: " code
  14357.       assign $KEY_CHECK old_kcheck       ;reset to original value
  14358.  
  14359.      NOTE: Various references to "extended key codes" are made in this
  14360.      document. "Extended" key codes are NUMERIC key codes below that are not
  14361.      specified in double quotes.  A regular press of the [A] key, or [Shift-
  14362.      A], or [Ctrl-A] are NOT extended key codes (you can see this by looking
  14363.      at the table below, noticing that all of these [A] key codes are between
  14364.      double quotes; "a", "A", "^A").  Of the various [Al key combinations,
  14365.      only [Alt-A] is an 'extended' key code (extended key code # 7680).  For
  14366.      commands or variables which specify that you MUST use an extended key
  14367.      code (the $HOTKEY_? variables for example), you cannot use any of the
  14368.      codes listed in double quotes below.  This is not permitted:
  14369.  
  14370.       assign $HOTKEY_1 "A"  ;[A] is not an extended key code
  14371.  
  14372.      This is fine:
  14373.  
  14374.       assign $HOTKEY_1 7680 ;[Alt-A] is an extended key code
  14375.  
  14376.      F.2  Example of Usage
  14377.  
  14378.      You must use the same format as listed in the tables below to test for
  14379.      various key strokes.  The following example tests for all possible
  14380.      combination of the [A] key:
  14381.  
  14382.       variable code
  14383.       assign $KEY_CHECK 0   ;Necessary when checking for EXTENDED key codes
  14384.                             ; which Icom uses for some function.  Most
  14385.                             ; extended key codes ARE used by Intellicomm for
  14386.                             ; various functions.  Below we're checking for
  14387.                             ; [Alt-A], and since Icom uses [Alt-A] for "Text
  14388.                             ; Editor" we have to TELL Intellicomm not to
  14389.                             ; process any extended keys, or Icom will simply
  14390.                             ; enter the Text Editor if the user presses [Alt-
  14391.                             ; -A]
  14392.  
  14393.       printnc "Press [a], [Shift-a], [Ctrl-a], or [Alt-a]: "
  14394.       inkeyw code
  14395.       assign $KEY_CHECK 1   ;allow Icom to process extended key codes again
  14396.  
  14397.       if code = "a"  print "[a] was pressed"
  14398.       if code = "A"  print "[Shift-a] was pressed"
  14399.       if code = "^A" print "[Ctrl-a] or [Ctrl-A] was pressed"
  14400.       if code = 7680 print "[Alt-a] or [Alt-A] was pressed"
  14401.  
  14402.      Note that for [Ctrl] and [Alt] key combinations, [Alt-A] is the same as
  14403.      [Alt-a], and [Ctrl-A] is the same as [Ctrl-a] (case is not significant). 
  14404.  
  14405.  
  14406.  
  14407.  
  14408.      Intellicomm v2.01               SCRIPT.DOC                            230
  14409.      
  14410.      
  14411.  
  14412.      UPPERCASE/lowercase applies only to the 'Norm' and 'Shift' columns.
  14413.      If the [Caps Lock] is enabled, 'Norm' and 'Shift' will be reversed (i.e.
  14414.      a normal [a] keypress is "A" and a [Shift-a] keypress is "a").  In most
  14415.      cases, if you want to check for an [A] keypress, you'll check for both
  14416.      "a" and "A" so that the user can ignore the state of the [Caps Lock] key:
  14417.  
  14418.        variable key
  14419.  
  14420.        inkeyw key
  14421.        switch key
  14422.          case "A"
  14423.          case "a"
  14424.            ...      ;do something for either case, UPPER or lower
  14425.          endcase
  14426.          case "B"
  14427.          case "b"
  14428.            ...
  14429.          endcase
  14430.          ...etc
  14431.        endswitch
  14432.  
  14433.      The state of the [Num Lock] key also affects the keys on the numeric
  14434.      keypad, as discussed below.
  14435.  
  14436.      NOTE: Where "N/A" (not applicable) is listed below, it means that the
  14437.      keyboard hardware is not capable of returning a key code for a given
  14438.      state.  For example, [Ctrl-1] doesn't return any key code at all, and
  14439.      such a key press will not even been seen by INKEY, INKEYW, INKEYT.  N/A
  14440.      keys are a limitation of PC keyboard hardware and not of Intellicomm's
  14441.      script language.... just as the numbers returned by various keys are
  14442.      simply what PC hardware uses and are not assigned by the script language
  14443.      (the same numbers will work in a real program, or in any other script
  14444.      language that uses the regular keyboard scan codes).
  14445.  
  14446.      Key    Norm     Shift    Ctrl      Alt 
  14447.      ---------------------------------------------------------------
  14448.       A       "a"      "A"     "^A"     7680
  14449.       B       "b"      "B"     "^B"    12288
  14450.       C       "c"      "C"     "^C"    11776
  14451.       D       "d"      "D"     "^D"     8192
  14452.       E       "e"      "E"     "^E"     4608
  14453.       F       "f"      "F"     "^F"     8448
  14454.       G       "g"      "G"     "^G"     8704
  14455.       H       "h"      "H"     "^H"     8960
  14456.       I       "i"      "I"     "^I"     5888
  14457.       J       "j"      "J"     "^J"     9216
  14458.       K       "k"      "K"     "^K"     9472
  14459.       L       "l"      "L"     "^L"     9728
  14460.       M       "m"      "M"     "^M"    12800
  14461.       N       "n"      "N"     "^N"    12544
  14462.       O       "o"      "O"     "^O"     6144
  14463.       P       "p"      "P"     "^P"     6400
  14464.       Q       "q"      "Q"     "^Q"     4096
  14465.       R       "r"      "R"     "^R"     4864
  14466.  
  14467.  
  14468.  
  14469.  
  14470.      Intellicomm v2.01               SCRIPT.DOC                            231
  14471.      
  14472.      
  14473.  
  14474.       S       "s"      "S"     "^S"     7936
  14475.       T       "t"      "T"     "^T"     5120
  14476.       U       "u"      "U"     "^U"     5632
  14477.       V       "v"      "V"     "^V"    12032
  14478.       W       "w"      "W"     "^W"     4352
  14479.       X       "x"      "X"     "^X"    11520
  14480.       Y       "y"      "Y"     "^Y"     5376
  14481.       Z       "z"      "Z"     "^Z"    11264
  14482.       1       "1"      "1"      N/A    30720
  14483.       2       "2"      "2"      768    30976
  14484.       3       "3"      "3"      N/A    31232
  14485.       4       "4"      "4"      N/A    31488
  14486.       5       "5"      "5"      N/A    31744
  14487.       6       "6"      "6"      N/A    32000
  14488.       7       "7"      "7"      N/A    32256
  14489.       8       "8"      "8"      N/A    32512
  14490.       9       "9"      "9"      N/A    32768
  14491.       0       "0"      "0"      N/A    33024
  14492.       ,       ","      ","      N/A    13056
  14493.       .       "."      "."      N/A    13312
  14494.       /       "/"      "/"      N/A    13568
  14495.       ;       ";"      ";"      N/A     9984
  14496.       '       "'"      "'"      N/A    10240
  14497.       [       "["      "["     "^["     6656
  14498.       ]       "]"      "]"     "^]"     6912
  14499.       `       "`"      "`"      N/A    10496
  14500.       -       "-"      "-"     "^-"    33280
  14501.       =       "="      "="      N/A    33536
  14502.       \       "\"      "\"     "^\"    11008
  14503.  
  14504.      Key    Norm     Shift    Ctrl      Alt 
  14505.      ---------------------------------------------------------------
  14506.      F1     15104    21504    24064    26624
  14507.      F2     15360    21760    24320    26880
  14508.      F3     15616    22016    24576    27136
  14509.      F4     15872    22272    24832    27392
  14510.      F5     16128    22528    25088    27648
  14511.      F6     16384    22784    25344    27904
  14512.      F7     16640    23040    25600    28160
  14513.      F8     16896    23296    25856    28416
  14514.      F9     17152    23552    26112    28672
  14515.      F10    17408    23808    26368    28928
  14516.      F11    34048    34560    35072    35584
  14517.      F12    34304    34816    35328    35840
  14518.      Enter   "^M"     "^M"     "^J"     7168
  14519.      Ins    20992    20992    37376    41472
  14520.      Del    21248    21284    37632    41728
  14521.      Esc     "^["     "^["     "^["      256
  14522.  
  14523.      NOTE: The values in the table below assume that [Num Lock] is OFF.  If
  14524.      [Num Lock] is ON, and the numeric keypad [Home], [End], etc., keys are
  14525.      used, the 'Norm' and 'Shift' fields will be REVERSED.  I.e. if [Num Lock]
  14526.      is ON, [Home] will be key code "7" and [Shift-Home] will be key code
  14527.      18176.
  14528.  
  14529.  
  14530.  
  14531.  
  14532.      Intellicomm v2.01               SCRIPT.DOC                            232
  14533.      
  14534.      
  14535.  
  14536.      The extended cursor control keys on AT-type keyboards (the cursor keys
  14537.      that are separated from the numeric keypad) return the same value for
  14538.      both 'Norm' and 'Shift', regardless of the state of [Num Lock].  I.e.
  14539.      whether [Num Lock] is on OR off, the extended [Home] key will always
  14540.      return 18176, and [Shift-Home] will also return 18176.  Extended or
  14541.      "enhanced" (101 key) keyboard hardware DOES make a distinction between
  14542.      the extended cursor control key codes, and the numeric keypad cursor
  14543.      control key codes.  Intellicomm's keystroke handler simulates the same
  14544.      key code for either though (either the extended [Home] key or the numeric
  14545.      keypad [Home] key for example), to simplify keyboard handling.
  14546.  
  14547.      Key    Norm     Shift    Ctrl      Alt 
  14548.      ---------------------------------------------------------------
  14549.      Home   18176      "7"    30464    38656
  14550.      End    20224      "1"    29952    40704
  14551.      PgUp   18688      "9"    33792    39168
  14552.      PgDn   20736      "3"    30208    41216
  14553.      Up     18432      "8"    36096    38912
  14554.      Down   20480      "2"    37120    40960
  14555.      Left   19200      "4"    29440    39680
  14556.      Right  19712      "6"    29696    40192
  14557.      Tab     "^I"     3840    37888    42240
  14558.      BckSpc  "^H"     "^H"      " "     3584
  14559.      Kpad 5 19456      "5"    36608      N/A
  14560.      Grey *  "*"       "*"    38400      N/A
  14561.      Grey -  "-"       "-"    36352    18944
  14562.      Grey +  "+"       "+"    36864    19968
  14563.  
  14564.  
  14565.  
  14566.  
  14567.      Intellicomm v2.01               SCRIPT.DOC                            233
  14568.      
  14569.      
  14570.  
  14571.                         G.  SCRIPT ERROR MESSAGES/SOLUTIONS
  14572.  
  14573.      Error : "OPERATOR is an invalid operator; =, <>, <, <=, >, >= only"
  14574.      Reason: An invalid operator was specified in an IF or WHILE command. 
  14575.              Valid operators are =, <>, <, <=, >, >=.  See IF in the Detailed
  14576.              Command Summary for details.
  14577.  
  14578.      Error : "Parameter missing in IF/WHILE"
  14579.      Reason: An operator was specified (<, <=, =, >= >) but no parameter
  14580.              followed to carry out the comparison.  Add an argument after your
  14581.              operator.  E.g. 'IF X = ' is illegal, 'IF X = 1' is fine.
  14582.  
  14583.      Error : "No ']' in BIF Variable"
  14584.      Reason: *[ (the BIF variable *[X]tag prefix) was specified but no closing
  14585.              ']' was found.  Ensure that you have a closing bracket in the
  14586.              variable and that there are no spaces ('*[ X ]tag' is illegal;
  14587.              use '*[X]tag').
  14588.  
  14589.      Error : "Bad section [X] in BIF Variable"
  14590.      Reason: The section (*[X]tag) specified in a BIF Variable was unknown. 
  14591.              See BIF Variable Appendix for details.
  14592.  
  14593.      Error : "Bad tag [sTAG] in BIF Variable"
  14594.      Reason: The sTAG (*[X]sTAG) specified in a BIF Variable was unknown.  See
  14595.              BIF Variable Appendix for details.
  14596.  
  14597.      Error : "Bad tag [sTAG] in INI Variable"
  14598.      Reason: A bad main setup tag followed the asterisk in a variable
  14599.              specification (*tag).  See the Main Setup Variables appendix for
  14600.              valid tags.
  14601.  
  14602.      Error : "No command with WHEN"
  14603.      Reason: A prompt string was specified with WHEN, but no command was
  14604.              specified (the command to execute when the prompt is found).  Add
  14605.              a command after the prompt.
  14606.  
  14607.      Error : "cCOMMAND command/label not found"
  14608.      Reason: cCOMMAND is not a recognized command or label.  Check the
  14609.              command/label carefully for typing errors.
  14610.  
  14611.      Error : "LABELNAME label not found."
  14612.      Reason: The label following GOTO or GOSUB was not found in the script. 
  14613.              Check the label carefully for typing errors.
  14614.  
  14615.      Error : "cCOMMAND requires a VARIABLE as the first parameter"
  14616.      Reason: The first paremter following cCOMMAND was not a variable.  Script
  14617.              commands that assign or change data require a variable as their
  14618.              first parameter.  Either define a variable using the VARIABLE
  14619.              command, and specify the variable's name as the first parameter
  14620.              following cCOMMAND, or use a GlobalStr[] or read/write System
  14621.              Variable as the first parameter.
  14622.  
  14623.      Error : "cCOMMAND called before MENUDEFINE"
  14624.      Reason: MENUBAR, MENUBOXH, or MENUBOXV was executed before MENUDEFINE was
  14625.  
  14626.  
  14627.  
  14628.  
  14629.      Intellicomm v2.01               SCRIPT.DOC                            234
  14630.      
  14631.      
  14632.  
  14633.              used.  See MENUDEFINE in the Detailed Command Summary for
  14634.              details.
  14635.  
  14636.      Error : Menu item [nITEM] is invalid [no such item]
  14637.      Reason: An invalid menu item number was specified in a MENUHLP command. 
  14638.              See MENUHLP in the Detailed Command Summary for details.
  14639.  
  14640.      Error : "Bad GOTO/GOSUB; No label/variable name"
  14641.      Reason: GOTO or GOSUB was used, but no label name followed.  Specify a
  14642.              label to jump to after the GOTO or GOSUB command.
  14643.  
  14644.      Error : "Bad GOTO/GOSUB; Bad 1st character in label/variable name"
  14645.      Reason: The first character in the label name following the GOTO or GOSUB
  14646.              command is invalid.  The first character in a label name must be
  14647.              in the range a-z, A-Z or an underscore (_).  Numbers are not
  14648.              valid first characters in label names.
  14649.  
  14650.      Error : "Bad GOTO/GOSUB; Bad character [X] in label/variable name"
  14651.      Reason: An invalid character was used in a label name.  You may only use
  14652.              alphanumeric characters (a-z, A-Z, 0-9) and underscores (_) in
  14653.              script labels.
  14654.  
  14655.      Error : "Can't define vVARIABLE; No label/variable name"
  14656.      Reason: No variable label name was specified after the VARIABLE command. 
  14657.              You must specify a legal variable name after the VARIABLE command
  14658.              (see 'Bad 1st character' and 'Bad character' just below for
  14659.              information on valid variable names).
  14660.  
  14661.      Error : "Can't define vVARIABLE; Bad 1st character in label/variable
  14662.              name"
  14663.      Reason: The first character in the variable name following the VARIABLE
  14664.              command is invalid.  The first character in a variable name must
  14665.              be in the range a-z, A-Z or an underscore (_).  Numbers are not
  14666.              valid first characters in variable names.
  14667.  
  14668.      Error : "Can't define vVARIABLE; Bad character [c] in label/variable
  14669.              name"
  14670.      Reason: An invalid character was used in a variable name.  You may only
  14671.              use alphanumeric characters (a-z, A-Z, 0-9) and underscores (_)
  14672.              in script variable names.
  14673.  
  14674.      Error : "Can't define vVARIABLE; Max variables reached"
  14675.      Reason: The variable table is full.  No more than 35530 variables may be
  14676.              defined in any one script.  See the SCRIPT MEMORY LIMITS appendix
  14677.              below for possible solutions.  If you split your script up into
  14678.              two or more scripts, you can define more than 35530 variables
  14679.              total.
  14680.  
  14681.      Error : "Can't define vVARIABLE; No memory"
  14682.      Reason: The computer is out of memory and there was none left to allocate
  14683.              the variable.  Reduce the number of variables in your script by
  14684.              using global 'working' variables which you use throughout the
  14685.              script.  For example, if you need to count from 1 to 10 in ten
  14686.              different places in your script, use the same variable to do the
  14687.  
  14688.  
  14689.  
  14690.  
  14691.      Intellicomm v2.01               SCRIPT.DOC                            235
  14692.      
  14693.      
  14694.  
  14695.              counting instead of defining separate variables each time.
  14696.  
  14697.      Error : "Can't define vVARIABLE; Variable exists"
  14698.      Reason: The variable name following the VARIABLE command has already been
  14699.              defined elsewhere in the script.  Use a different variable name.
  14700.  
  14701.      Error : "Can't define vVARIABLE; Name duplicates a script COMMAND"
  14702.      Reason: To allow for future script enhancements, variable names cannot
  14703.              duplicate script commands.  For example, 'VARIABLE variable' is
  14704.              illegal since the variable name ('variable') duplicates the
  14705.              VARIABLE command.  Use another variable name.
  14706.  
  14707.      Error : "Can't assign data to vVARIABLE; no memory"
  14708.      Reason: The computer is out of memory and there was none left to allocate
  14709.              data to a defined variable.  Memory for variables is allocated
  14710.              based on the length of the data assigned to a variable, and the
  14711.              total number of variables.  Reduce the number of variables in
  14712.              your script by using global 'working' variables which you use
  14713.              throughout the script.  For example, if you need to count from 1
  14714.              to 10 in ten different places in your script, use the same
  14715.              variable to do the counting instead of defining separate
  14716.              variables each time.
  14717.  
  14718.      Error : "Undefined variable; vVARIABLE"
  14719.      Reason: A variable name was specified, but it does not exist.  Check the
  14720.              variable name carefully to ensure that you have defined it with
  14721.              the VARIABLE command (or see the BIF Variables / Main Setup
  14722.              Variables appendices if applicable).
  14723.  
  14724.      Error : "vVARIABLE variable is read only"
  14725.      Reason: You attempted to assign data to a read only $SYSTEM variable. 
  14726.  
  14727.      Error : "GlobalStr missing ]"
  14728.      Reason: 'GlobalStr[' was specified but no closing ']' was found.  Ensure
  14729.              that you have a closing bracket in the variable and that there
  14730.              are no spaces ('GlobalStr[ X ]' is illegal; use 'GlobalStr[X]').
  14731.  
  14732.      Error : "GlobalStr[nOFFSET] is out of bounds [0-9 only]"
  14733.      Reason: The offset specified between the GlobalStr brackets is invalid. 
  14734.              Valid offsets are numbers from 0-9 only.
  14735.  
  14736.      Error : "Invalid variable in GlobalStr; vVARIABLE"
  14737.      Reason: A variable name was specified as the GlobalStr offset (e.g.
  14738.              GlobalStr[variable_name]) but variable_name is invalid.  Only
  14739.              user-defined variables are valid as GlobalStr offsets.  Define
  14740.              the variable with the VARIABLE command before using it in
  14741.              GlobalStr.
  14742.  
  14743.      Error : "Not enough memory ... Can't perform function."
  14744.      Reason: All of the computer's memory has been used up.  This is a general
  14745.              purpose error message that can occur with many script commands,
  14746.              and the only solution is to reduce the size of your script (see
  14747.              the SCRIPT MEMORY LIMITS appendix below), or to increase the
  14748.              amount of memory on your computer (use MEMMAKER, QEMM, etc). 
  14749.  
  14750.  
  14751.  
  14752.  
  14753.      Intellicomm v2.01               SCRIPT.DOC                            236
  14754.      
  14755.      
  14756.  
  14757.              Note that memory above 640K is not useable by DOS programs or
  14758.              scripts, so the only way to make 'more' memory available is to
  14759.              move device drivers and TSR's out of conventional memory, and
  14760.              into upper memory.
  14761.  
  14762.      Error : "Division by zero"
  14763.      Reason: One of the parameters in the DIV(ide) command is zero.  Division
  14764.              by zero is invalid and you must change the offending parameter to
  14765.              a non-zero value.
  14766.  
  14767.      Error : "GOSUB stack overflow [16 GOSUB maximum]"
  14768.      Reason: GOSUB was executed more than 16 times before a RETURN was found. 
  14769.              When GOSUB's are executed, the script address (line number) to
  14770.              jump to when a RETURN is found is stored in an internal script
  14771.              'stack'.  This stack is only capable of holding 16 RETURN
  14772.              addresses.  You must simplify your script logic to solve the
  14773.              problem.
  14774.  
  14775.      Error : "FOPEN stack overflow [16 FOPEN maximum]"
  14776.      Reason: You attempted to FOPEN more than 16 files at a time.  Call FCLOSE
  14777.              to close one or more files before the offending FOPEN.
  14778.  
  14779.      Error : "FOPEN mode "%s" is invalid [r, w, a, r+, w+, a+ only]"
  14780.      Reason: The mode specified in the FOPEN command (3rd parameter) was
  14781.              invalid.  See FOPEN in the Detailed Command Summary for details.
  14782.  
  14783.      Error : "nHANDLE is an invalid file number"
  14784.      Reason: The file handle specified in a file-related command (FGETS,
  14785.              FPUTS, FCLOSE, etc) is invalid.  You must obtain a valid file
  14786.              handle with the FOPEN command before using file-related commands. 
  14787.              A given file handle is also invalid after FCLOSE is used on the
  14788.              file.
  14789.  
  14790.      Error : "cCOMMAND stack overflow."
  14791.      Reason: VPUSH was used more than 16 times before VPOP, WNDOPEN was used
  14792.              more than 16 times before WNDCLOSE, or WAITFOR was nested (likely
  14793.              via a 'WHEN "text" gosub subroutine' command where WAITFORs are
  14794.              used in the subroutine) more than 16 times.
  14795.  
  14796.      Error : "BREAK|CONTINUE|ENDWHILE without WHILE"
  14797.      Reason: BREAK CONTINUE or ENDWHILE was found, but no WHILE was specified.
  14798.  
  14799.      Error : "ELSE|ENDIF without IF"
  14800.      Reason: ELSE or ENDIF was found, but no IF was specified.
  14801.  
  14802.      Error : "DEFAULT|ENDCASE|ENDSWITCH without SWITCH"
  14803.      Reason: DEFAULT ENDCASE or ENDSWITCH was found, but no SWITCH was
  14804.              specified.
  14805.  
  14806.      Error : "Must COPEN a catalog before cCOMMAND"
  14807.      Reason: Attempted a catalog-related command (CGETREC, etc) but no catalog
  14808.              was open.  Use COPEN before the command.
  14809.  
  14810.      Error : "Catalog must be sorted [CSETSORT] before export"
  14811.  
  14812.  
  14813.  
  14814.  
  14815.      Intellicomm v2.01               SCRIPT.DOC                            237
  14816.      
  14817.      
  14818.  
  14819.      Reason: Attempted a CEXPORT on an unsorted catalog.  Use CSETSORT before
  14820.              the CEXPORT command.
  14821.  
  14822.      Error : "Invalid sort order"
  14823.      Reason: Tried to CSAVESORT with no sort order defined.  Use CSETSORT
  14824.              before calling CSAVESORT.
  14825.  
  14826.  
  14827.  
  14828.  
  14829.      Intellicomm v2.01               SCRIPT.DOC                            238
  14830.      
  14831.      
  14832.  
  14833.                               H.  SCRIPT MEMORY LIMITS
  14834.  
  14835.      To execute a script, Intellicomm first checks the filesize of the script
  14836.      file (as reported by the filesize you'd see in a DOS 'DIR' listing, and
  14837.      in the Script Manager to the right of the script filename).  If less than
  14838.      65530 bytes, Icom then attempts to allocate a memory buffer (the same
  14839.      size as the script filesize) to put the script into.  If enough memory is
  14840.      available, the script is read into the newly allocated memory buffer all
  14841.      in one shot with no stripping of comments, trailing spaces, or blank
  14842.      lines.  This is done mainly for speed, since many Icom scripts are used
  14843.      to enter a few characters quickly, or to enter a command from a BIF, or
  14844.      as a simple script for small custom jobs/logons, etc.  In these cases
  14845.      speed counts, and wasting memory isn't an issue since the scripts are
  14846.      small.
  14847.  
  14848.      H.1  Developing Large Scripts
  14849.  
  14850.      If you are developing a large script that won't load into memory due to
  14851.      the 64K (65530 byte) limit, a fairly easy solution is to split your
  14852.      script up into smaller scripts and use the SCRIPT command to call the
  14853.      smaller scripts if/when they're needed.  *Each* script is allowed 65530
  14854.      bytes of memory (up to the limit of available DOS memory -- usually
  14855.      640K).  By using multiple scripts you can use all the DOS memory
  14856.      available on the computer.  Here's an example of how it works:
  14857.  
  14858.      ;MAIN.SCR this is the main 'module' of your script program
  14859.      ; (you don't have to call it MAIN.SCR... it can be any name)
  14860.  
  14861.      ;here we call a series of other scripts to do what needs doing
  14862.      SCRIPT "LOGON.SCR"    ;LOGON.SCR might dial and logon the BBS
  14863.      OFFLINE GOTO done     ;if not connected, quit
  14864.  
  14865.      SCRIPT "DOWORK1.SCR"  ;perform some task with another script
  14866.      OFFLINE GOTO done     ;if not connected, quit
  14867.  
  14868.      SCRIPT "DOWORK2.SCR"  ;perform another task with another script
  14869.      OFFLINE GOTO done     ;if not connected, quit
  14870.       ...                  ;etc.
  14871.      done:
  14872.       return
  14873.  
  14874.      This is actually how many .EXE programs work as well, since there's
  14875.      usually no need to have ALL of the code in memory at the same time. 
  14876.      Whatever code is needed for the current task is loaded, and when that
  14877.      task finishes the code is unloaded, and the memory is freed up for use by
  14878.      the next task (which is exactly what happens when a script ends ... the
  14879.      memory it was using is freed up).  You need only a small control 'module'
  14880.      (the MAIN.SCR above) to swap other scripts in and out of memory as
  14881.      needed.  This technique also makes your code easier to follow and
  14882.      maintain, since it's easier to find things in smaller scripts.
  14883.  
  14884.      If you'd like to use this technique you should first refer to the
  14885.      SCRTUTOR.DOC sections: "Global Variables" and "Passing Parameters to
  14886.      Scripts" if you haven't already.  The Global Variables can be very useful
  14887.  
  14888.  
  14889.  
  14890.  
  14891.      Intellicomm v2.01               SCRIPT.DOC                            239
  14892.      
  14893.      
  14894.  
  14895.      for inter-script communication (telling the called script what to do). 
  14896.      As well you might consider using the $ERRORLEVEL System Variable to
  14897.      return various errorcodes to your main module.  You're free to ASSIGN an
  14898.      errorcode that would be meaningful to the main module prior to exiting
  14899.      the called script.  For example, $ERRORLEVEL 1 might mean the carrier was
  14900.      lost.  $ERRORLEVEL 2 might mean that a BBS event was scheduled, etc. 
  14901.      Just use ASSIGN $ERRORLEVEL x (where x is your return code) in the called
  14902.      script, then use IF $ERRORLEVEL = x (where x is the errorcode) or SWITCH
  14903.      $ERRORLEVEL to TEST for any abort codes when the called scripts return.
  14904.  
  14905.      You should also be aware of the difference between the EXIT and RETURN
  14906.      command as it applies to called scripts.  The EXIT command aborts ALL
  14907.      scripts (exits the script interpreter entirely), while RETURN simply ends
  14908.      the current script, returning control to the caller.  So, in the example
  14909.      above, if something went desperately wrong in the logon you could use an
  14910.      EXIT command in LOGON.SCR to cancel both LOGON.SCR *and* MAIN.SCR, and
  14911.      return to manual mode.  Alternatively the RETURN command simply exits the
  14912.      current script and returns control to the caller at the next line below
  14913.      the SCRIPT command.
  14914.  
  14915.      You can also specify 'errorcodes' after the EXIT and RETURN commands to
  14916.      tell Intellicomm what to do with the current automated job (if the
  14917.      original script was called from an automated job via a Custom Command or
  14918.      BIF).  EXIT or RETURN followed by a positive number (1, 2, etc) tells
  14919.      Icom to hangup and remove the current BIF from the job queue (useful if
  14920.      you encounter a BBS 'event' and you have no time online, etc).  EXIT or
  14921.      RETURN followed by a negative number (-1, -2, etc) causes Icom to abort
  14922.      ALL jobs, just as if the user had selected "Abort Job/Script" from the
  14923.      [Alt-Q] menu.  There are several considerations for using errorcodes with
  14924.      EXIT and RETURN, and more details can be found in section ?.
  14925.  
  14926.  
  14927.                     I.  CREATING SCRIPTS FOR PUBLIC DISTRIBUTION
  14928.  
  14929.      This section is for script "gurus" or prospective gurus who have a script
  14930.      project in-mind that they plan to distribute to the general public. 
  14931.      These are ONLY pointers... They are not 'rules', and you can feel free to
  14932.      ignore every one of them if you like.
  14933.  
  14934.      First off, some no-no's for public distribution:
  14935.  
  14936.       o Don't make the installation and setup unnecessarily complicated.  It
  14937.         not only turns people off right at that crucial "first impression"
  14938.         moment, but can cause you grief if you offer technical support.
  14939.  
  14940.       o Don't use your own custom colors in your script, no matter how nice it
  14941.         looks on your screen.  Monochrome and laptop displays cannot display
  14942.         all colors properly and if you hardcode in custom colors, your script
  14943.         may be useless to many people.  Use the various $xxxx_COLOR System
  14944.         Variables to specify colors to display with the colors the user has
  14945.         set up in the Icom main setup.  Better yet, use WNDOPEN, MSGOPEN,
  14946.         PRINT, etc., to display text on the screen, which automatically use
  14947.         the default Icom colors.
  14948.  
  14949.  
  14950.  
  14951.  
  14952.      Intellicomm v2.01               SCRIPT.DOC                            240
  14953.      
  14954.      
  14955.  
  14956.       o If you use an 'extended' (43 or 50) line video mode in the Icom main
  14957.         setup, make sure you set the display for standard 25 line mode and re-
  14958.         test your script before distribution.  You may have defined menus or
  14959.         other screens that will not fit on other people's video displays if
  14960.         you used an extended line mode when developing your script.
  14961.  
  14962.       o Try to make as many things as possible configurable (see the
  14963.         INTRODUCTION TO FILE INPUT / OUTPUT for information on storing data
  14964.         on-disk), and avoid hardcoding specific drives and directories.  Use
  14965.         the System Variables, BIF Variables, and Main Setup Variables to get
  14966.         the Icom data the USER has already set up where possible.
  14967.       
  14968.      Now some 'do's:
  14969.  
  14970.       o Create an @ICOM.SCR installation script and include it in your
  14971.         archive.  Icom's POSTFILE.SCR, which automatically decompresses and
  14972.         virus checks new downloads, also checks for a script called @ICOM.SCR. 
  14973.         If it's found (i.e. if you include it in your distribution archive),
  14974.         the user is given the option to execute it.  Thus, you can LIST
  14975.         "README.TXT", COPY or RENAME (move) your files to install them
  14976.         AUTOMATICALLY, get information from the user, etc., using @ICOM.SCR. 
  14977.         Basically anything that needs doing for installation and setup up of
  14978.         your product can be done automatically via @ICOM.SCR.
  14979.  
  14980.       o Test your script thoroughly before releasing it, attempting to look at
  14981.         it from a new user's perspective.
  14982.  
  14983.       o Document features that aren't obvious.  Implement online help were
  14984.         possible (the LIST command will allow you to display your
  14985.         documentation while your script is running, which is as good as online
  14986.         help).
  14987.  
  14988.       o You're free to support your scripts (and take complements on your
  14989.         work) in any of the online forums we use for Intellicomm.  Make
  14990.         yourself available for feedback, if possible.
  14991.  
  14992.       o If your script is has its own interface, or is otherwise "stand-
  14993.         alone", the best way to run it is via the DOS command line with the
  14994.         /scr: switch.  If you include a .BAT file with your script, you can
  14995.         have users start it right from DOS (or Windows/DESQview or a menu
  14996.         system) just as they would a regular program:
  14997.  
  14998.          Echo off
  14999.          rem MYSCRIPT.BAT starts MYSCRIPT.SCR from DOS
  15000.          ICOM.EXE /scr:myscript
  15001.  
  15002.       o Pass along your feedback as to where you'd like to see improvements or
  15003.         changes in the script language.  Implementing new script commands
  15004.         (particularly if you're a C programmer and you know that it's a
  15005.         standard library function) is usually very simple.  New script
  15006.         concepts and rules are more complicated to code (and particularly to
  15007.         implement, without rendering all scripts to date useless), but all
  15008.         suggestions will be considered.
  15009.  
  15010.  
  15011.  
  15012.  
  15013.      Intellicomm v2.01               SCRIPT.DOC                            241
  15014.      
  15015.      
  15016.  
  15017.                      J.  CHANGES FROM THE V1.00 SCRIPT LANGUAGE
  15018.  
  15019.      Listing all the changes from the Icom v1.00 script language would be
  15020.      pointless, since it would duplicate most of this manual to explain them
  15021.      all.  By reading the introductory material in SCRTUTOR.DOC, and looking
  15022.      at the SCRIPT COMMANDS AT A GLANCE section, you'll be able to pick up all
  15023.      the changes and new commands quickly.  This section covers only the
  15024.      changes that are relevant to existing v1.00 scripts.  All v1 script
  15025.      commands, other than those listed below, work the same with Icom v2 as
  15026.      they did with v1.
  15027.  
  15028.      J.1  Version 2 Syntax Changes
  15029.  
  15030.      Single quotes are no longer permitted around string constants.  With the
  15031.      v1 script language this was legal:
  15032.  
  15033.       PRINT 'This string has "double" quotes in it.'
  15034.  
  15035.      The problem with this is that you cannot use both single AND double
  15036.      quotes in a string.  With the addition of File I/O, where data is read
  15037.      from a text file (data which could contain both single and double quotes
  15038.      on a single line) this this is no longer practical.  Thus, you must use
  15039.      DOUBLE quotes around string constants, and if a double quote appears in
  15040.      the text, use a caret to escape it:
  15041.  
  15042.       PRINT "This string has ^"double^" quotes in it."
  15043.  
  15044.      J.2  Version 2 Command Changes
  15045.  
  15046.      EXIST, NOTEXIST, OFFLINE, ONLINE, and WHEN
  15047.      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15048.      These commands no longer force you to GOTO a script label.  You can now
  15049.      use any script command after any of these commands.  Examples:
  15050.  
  15051.       EXIST "somefile.ext" DELETE "somefile.ext"
  15052.       NOTEXIST "somefile.ext" GOTO done
  15053.       OFFLINE EXIT 
  15054.       ONLINE MSGWIND "You are online"
  15055.       WHEN "find this" SEND "command"
  15056.       WHEN "find that" GOSUB handle_find_that
  15057.       WHEN "Begin your Download" DOWNLOAD "Z" ""
  15058.  
  15059.      The addition of the GOSUB command, combined with the ability to use GOSUB
  15060.      in WHENs should be quite helpful in writing your scripts.  If you use a
  15061.      GOSUB in a WHEN, the script executes the subroutine (until a RETURN is
  15062.      encountered) then returns to the WAITFOR.  Thus you can handle much more
  15063.      complex tasks with WHEN/WAITFOR than you could with the v1 script
  15064.      language.
  15065.  
  15066.      Further, EXIST and NOTEXIST now search for read-only files as well as
  15067.      normal files (but not hidden files, subdirectories, DOS system files, or
  15068.      the volume ID).  Previously, EXIST and NOTEXIST found only files that
  15069.      were normal (not read-only).  You can now also access all the file
  15070.      attributes of files found with EXIST (if the file exists) including file
  15071.  
  15072.  
  15073.  
  15074.  
  15075.      Intellicomm v2.01               SCRIPT.DOC                            242
  15076.      
  15077.      
  15078.  
  15079.      size, file modification date and time, and file attributes via the System
  15080.      Variables $FSIZE, $FDAY, $FMONTH, $FYEAR, $FHOUR, $FMIN, $FSEC, and
  15081.      $FRDONLY.  You may also wish to replace some of your EXIST commands with
  15082.      the FINDFIRST command, which allows you to search for files with ANY
  15083.      attribute (including hidden files, subdirectories, DOS system files, and
  15084.      the disk volume ID).  Using FINDNEXT after a call to FINDFIRST allows you
  15085.      to obtain all filenames in a given wildcard (*.DBF, \ICOM\BIF\*.BIF,
  15086.      I???.*, etc), as well as the attributes of each file.
  15087.  
  15088.      EXIT
  15089.      ~~~~
  15090.      The EXIT command now exits the script processor entirely.  Previously if
  15091.      you used the SCRIPT command to call another script, and the called script
  15092.      performed an EXIT, it would simply return to the original script.  EXIT
  15093.      is now used to abort ALL scripts and return control to whatever called
  15094.      the original script (the automated job, or Script Manager, etc).  To exit
  15095.      only from the CURRENT script (i.e. to allow the calling script to
  15096.      continue running), use the RETURN command.  RETURN does take an optional
  15097.      exit code as EXIT does.  Please see section ? in SCRTUTOR.DOC and the
  15098.      Detailed Command Summaries of EXIT and RETURN above, for more details on
  15099.      usage.
  15100.  
  15101.      GOTOXY
  15102.      ~~~~~~
  15103.      A bug in the GOTOXY command was fixed for v2.0.  GOTOXY 1 1 went to
  15104.      screen position 2, 2 with Icom v1.00.  The v1 script conversion utility
  15105.      automatically decrements the screen coordinates in GOTOXY commands found
  15106.      in v1 scripts, to account for this bug fix.
  15107.  
  15108.      SCAPTURE
  15109.      ~~~~~~~~
  15110.      This command now takes a parameter that allows you to specify a
  15111.      D:\PATH\FILENAME.EXT to capture to, instead of forcing the screen capture
  15112.      to the default Icom screen capture file.  If no filename follows
  15113.      SCAPTURE, the usual screen capture file (\ICOM\CAP\SCREEN.CAP by default;
  15114.      defined on the main setup/Filenames and Paths screen) is used, as with
  15115.      the v1 script language.
  15116.  
  15117.      SEND/SENDNC
  15118.      ~~~~~~~~~~~
  15119.      The SEND and SENDNC commands now observe any "Response Delay" you have
  15120.      set in the BIF (screen 1):
  15121.  
  15122.      | Receive Mail . .                       Response Delay . 10
  15123.                                               ~~~~~~~~~~~~~~~~~~~
  15124.      Since SEND is normally used in combination with a WHEN command to respond
  15125.      to a BBS prompt, and is also used by Script Learn mode after WAITFORs to
  15126.      send responses in learned scripts, a configurable response delay in the
  15127.      BIF can be very useful with certain BBS software.  Some BBS software
  15128.      clears the COM input buffer after displaying prompts, and if your script
  15129.      had sent the response BEFORE the buffer was cleared (i.e. if the script
  15130.      answers BEFORE the prompt is fully displayed), it would be lost. If your
  15131.      SEND or SENDNC commands are not being processed by the BBS, adding a
  15132.      Response Delay to the BIF should remedy the situation.
  15133.  
  15134.  
  15135.  
  15136.  
  15137.      Intellicomm v2.01               SCRIPT.DOC                            243
  15138.      
  15139.      
  15140.  
  15141.      The equivalent commands to the v1.00 SEND and SENDNC (no delay) are
  15142.      SENDNP (NP for No Pause) and SENDNCP (NCP for No CR or Pause).
  15143.  
  15144.      SYSTEM
  15145.      ~~~~~~
  15146.      The SYSTEM command now takes two parameters.  Parameter 1 (a number from
  15147.      0-2) tells Intellicomm what to do if connected: SYSTEM 1 hangs up, SYSTEM
  15148.      2 stays connected, SYSTEM 0 (or no parameter) asks the user whether to
  15149.      disconnect, if connected.  The second optional parameter allows you to
  15150.      specify an ERRORLEVEL when exiting, which can be tested from a .BAT file
  15151.      or similar.  If you use SYSTEM 0 1, then errorlevel 1 is returned to DOS
  15152.      and could be tested:
  15153.  
  15154.      rem  A .BAT to run your script from the command line
  15155.      ICOM.EXE /scr:myscript
  15156.      if errorlevel 2 <do this>
  15157.      if errorlevel 1 <do this>
  15158.  
  15159.      ...where <do this> was a valid batch command (GOTO, DELETE, etc).
  15160.  
  15161.      WHEN
  15162.      ~~~~
  15163.      Aside from the previously mentioned change to WHEN, you can now also
  15164.      track up to nineteen BBS prompts using WHENs instead of seventeen, the
  15165.      v1.00 limit.
  15166.  
  15167.      J.3  Icom v1.00 Script Conversion
  15168.  
  15169.      Version 1 scripts are optionally converted when you install Intellicomm. 
  15170.      Aside from making sure that there are DOUBLE QUOTES around all strings
  15171.      (necessary now that variables have been introduced), all the conversion
  15172.      does is to place GOTOs in the ONLINE, OFFLINE, etc., commands listed
  15173.      above, which no longer force a GOTO.  The more subtle changes with EXIT
  15174.      and CAPTURE are not checked, as they would be difficult to convert
  15175.      automatically.  You should give your converted scripts a once-over just
  15176.      to make sure they're doing what you want.
  15177.  
  15178.      If you converted your scripts during Icom v2 installation and want your
  15179.      original v1 scripts back for some reason, you'll find them renamed to
  15180.      *.OLD in the \ICOM\SCR directory.
  15181.